Gutenberg 區塊無效、主機快取 404 與主題版面限縮排查

整理日期：2026-05-04

狀況

在建置特定產品的 Landing Page、隱私權政策與服務條款頁面時，遇到了以下三個相互關聯的問題：

發布後網頁顯示 404：透過 WP REST API 成功建立並發布頁面，後台編輯也正常，但在瀏覽器直接輸入網址訪問時卻一直顯示 404 找不到網頁。
版面被嚴重壓縮與標題重複：頁面內容左右出現大量留白，整體被包在一個狹窄的卡片容器中，且頁面最上方出現了重複的主題預設大標題。
區塊無效警告：在後台打開頁面時，編輯器內的多個按鈕與連結區塊跳出「此區塊包含未預期或無效的內容」紅色警告。

先拆成幾層看

主機與快取層：404 狀態是由 WordPress 核心拋出，還是被伺服器快取機制（如 Varnish, Cloudflare）快取了發布之前的狀態。
主題設定與 Meta 欄位層：佈景主題（如 GeneratePress）的全域寬度限制如何套用至新頁面。為何 REST API 無法直接寫入主題的版面覆寫欄位（如關閉頁面標題、設定全寬等）。
Gutenberg 驗證機制層：自訂區塊（如 GenerateBlocks）在資料庫儲存的 HTML 標籤，與區塊 JavaScript 的 save() 預期輸出為何不一致。

最後發現

快取殘留 404：在新頁面尚未發布前，該網址曾被訪問過而產生了 404 頁面，此 404 狀態被伺服器端的 Varnish 快取記錄（快取時間長達數十小時）。因此頁面發布後，外部訪問依然讀取到舊的 404 快取。
主題 REST API 限制：佈景主題的版面設定（例如隱藏標題、全寬版面）是儲存在自訂的 Post Meta 中（如 _generate-disable-elements 等），這些 Meta 欄位因為沒有在 WP REST API 中註冊，因此無法直接透過 API 請求來更新。
區塊驗證錯誤的原因：
- 區塊類型錯誤：對於純文字的 <a> 連結按鈕，誤用了預期包裹子區塊的 generateblocks/element 區塊，導致 save() 輸出與編輯器預期不符。
- Inline Style 衝突：在區塊標記中直接寫入複雜的 JSON inline styles 會干擾特定區塊的驗證。
- 核心區塊屬性多餘：WordPress 核心的清單（List）或圖片（Image）區塊中若手動寫入 inline style="..." 屬性，會因為核心 save() 預設不輸出此屬性而判定為無效。

修正方式

1. 清除 Varnish 404 快取

利用終端機發送 PURGE 請求清除該網址在主機端的 Varnish 快取：

curl -X PURGE "https://example.com/seo-page"

2. 使用一次性 Snippet 寫入主題版面 Meta 並搭配 CSS 覆寫

執行 PHP 程式碼寫入 Post Meta：

$ids = array(211116, 211117, 211118); // 頁面 ID
foreach ($ids as $id) {
    update_post_meta($id, '_generate-sidebar-layout-meta', 'no-sidebar');
    update_post_meta($id, '_generate-disable-headline', '1');
    update_post_meta($id, '_generate-full-width-content', 'true');
}

CSS 覆寫全域 site-main 寬度限制：

/* 讓特定 LP 頁面打破全站 42rem 的寬度限制 */
.page-id-211116 .site-main,
.page-id-211116 .inside-article {
    max-width: none !important;
    margin: 0 !important;
    padding: 0 !important;
    background: transparent !important;
    box-shadow: none !important;
}

3. 重構 Gutenberg 區塊避開無效警告

改用 Text 區塊：將純文字連結按鈕由 generateblocks/element 改為 generateblocks/text，並指定 tagName: "a"。
分離樣式至 CSS：將按鈕的 inline styles 全部拿掉，改在區塊的 className 屬性中宣告自訂的 Class（如 my-custom-btn），並在附加 CSS 中控制其視覺。

標準標記結構：

<!-- wp:generateblocks/text {"uniqueId":"cf82e071","tagName":"a","htmlAttributes":{"className":"my-custom-btn","href":"#install"}} -->
<a class="gb-text gb-text-cf82e071 my-custom-btn" href="#install">立即下載</a>
<!-- /wp:generateblocks/text -->

(注意：class 必須寫滿 gb-text gb-text-{id} {custom-class} 三重格式以符合 GenerateBlocks 的驗證預期)

不建議先做的事

看到編輯器警告時，不要直接在後台點擊「嘗試復原」，因為如果原始 HTML 中的 inline styles 還在，即使暫時復原，下次儲存或編輯時依然會壞掉。
不要輕易為了版面設定去全域關閉 Varnish 快取，這會嚴重影響全站的響應速度與主機負載。

下次遇到可以先整理什麼

發生 404 網頁的 Response Headers（在 DevTools 的 Network 面板查看 x-cache 或 x-cache-age），確認是否由伺服器快取引起。
點擊編輯器無效區塊上的「轉換為 HTML」，比對「原本的 HTML」與「編輯器預期輸出（綠底 diff 顯示）」的字元差異。
儘量避免在 Gutenberg 區塊中直接塞入非標準的 inline styles，應善用 Class 選擇器搭配外掛的 CSS 管理器進行視覺樣式控制。