Rank Math FAQ 區塊驗證失敗與區塊程式碼自動產生器

整理日期：2026-03-30

狀況

當我們需要在 WordPress 頁面中以「程式碼編輯器」模式直接置入或大量產生 Rank Math FAQ 區塊（Gutenberg Block）時，編輯器內經常會跳出「此區塊包含未預期或無效的內容」的紅色錯誤警告，即便前台顯示似乎正常，但這會導致後續無法在後台編輯該區塊。

先拆成幾層看

檢查 Gutenberg 區塊在儲存時的結構設計，以及它是如何驗證儲存內容（Stored Content）與編輯器預期（Expected Output）的一致性。
比對「前端瀏覽器渲染出來的 HTML 程式碼」與「資料庫內儲存的 Gutenberg Block 原始 HTML 程式碼」是否有差異。
找出 Rank Math FAQ Block 的 save() 函式所輸出的精準 HTML 結構與 JSON 屬性格式。

最後發現

Gutenberg 編輯器在載入區塊時，會比對 HTML 註解（例如 ）中的 JSON 屬性與其內部的 HTML 實體。

Rank Math FAQ 區塊存在一個關鍵的雙重結構：

編輯器儲存端（save()）：輸出的 HTML 非常簡潔，每個問答項目僅標示 .rank-math-faq-item，無包裝層，且元素沒有任何 id。
前台渲染端（PHP Server-side Render）：在網頁前端，PHP 會將其包裝成 .rank-math-block、.rank-math-list，並將項目類別改為 .rank-math-list-item，甚至加上動態產生且尾部帶有空格的 id="faq-question-..."。

如果直接複製前端網頁的 HTML 貼回後台編輯器，Gutenberg 就會因為與 save() 預期結構不符而判定為「無效區塊」。

修正方式

要批次產生無錯誤的 Rank Math FAQ 區塊，不能手寫或複製前台 HTML，必須使用專用的工具腳本，同時產生 JSON Attributes 以及符合 save() 格式的 HTML 代碼。

以下為 Node.js 自動產生腳本的實作方式：

1. 產生器腳本（`generate-faq.mjs`）

#!/usr/bin/env node
import { readFileSync } from 'fs';

// 從標準輸入（stdin）讀取 JSON 格式的問答資料
const input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));

const questions = input.map((pair, i) => ({
  id: `faq-question-${Date.now() + i}`,
  title: pair.question,
  content: pair.answer,
  visible: true
}));

const itemsHtml = questions
  .map(
    (q) =>
      `<div class="rank-math-faq-item">` +
      `<h3 class="rank-math-question">${q.title}</h3>` +
      `<div class="rank-math-answer">${q.content}</div>` +
      `</div>`
  )
  .join('');

const html = `<div class="wp-block-rank-math-faq-block">${itemsHtml}</div>`;
const attrs = JSON.stringify({ questions });

// 輸出符合 Gutenberg 標準的區塊代碼
process.stdout.write(
  `<!-- wp:rank-math/faq-block ${attrs} -->\n${html}\n<!-- /wp:rank-math/faq-block -->\n`
);

2. 使用工作流程

將需要產生的 FAQ 問答整理為 JSON 格式（faq-source.json）：

[
  {
    "question": "常見問題一的標題？",
    "answer": "常見問題一的解答內容。"
  }
]

在終端機執行腳本並複製結果：
終端機視窗
```
node generate-faq.mjs < faq-source.json | pbcopy
```
在 WordPress 區塊編輯器切換到「程式碼編輯器（Code Editor）」，直接貼上複製的程式碼，即可完美通過驗證且無警告。

不建議先做的事

絕對不要在編輯器警告「區塊無效」時，直接點擊「轉換為 HTML」，這會將整個區塊轉成裸 HTML 區塊，導致失去 Rank Math 的結構化資料（JSON-LD Schema）輸出功能，對 SEO 會造成負面影響。

下次遇到可以先整理什麼

點擊編輯器無效區塊上的「嘗試復原（Attempt Block Recovery）」，在主控台（Console）中觀察「期待的 HTML 結構」與「實際儲存的 HTML 結構」之間的差異。
任何 Gutenberg 自訂區塊（特別是包含 JSON attributes 的區塊），都應優先以 save() 的規範來產出 HTML，而非比照前端渲染結果。