三個錯誤佔了大多數 JSON-LD 檢查器提取失敗的原因：貼上錯誤的 HTML 原始碼、把乾淨的提取結果當作複合式搜尋結果的保證，以及把解析錯誤和缺少屬性的警告當成單一訊號。像 結構化資料檢查器與提取工具 這類以貼上內容為基礎的檢查器只會檢視你餵給它的內容，因此你選擇的輸入就是整個結果的基礎。如果標記是在用戶端產生的，爬蟲永遠看不到瀏覽器看到的內容；如果你部署的是某個模板，卻檢查另一個變體，提取所描述的就是 Google 並未索引的頁面。解析錯誤、Microdata 空白以及缺少屬性的警告分屬三個不同的證據類別；用錯誤的順序去修復它們是第二個經典錯誤。第三個則是把乾淨的提取結果當成符合資格的證明。一個 JSON-LD 物件可以完美解析、宣告正確的類型、顯示某個功能所需的所有屬性，卻仍可能因為可見內容不符、隱藏標記或不支援的功能用法而被取消資格。依照政策與模板本身來解讀提取結果，才能讓這個工具從一個綠色勾選符變成真正的洞察。
在你貼上之前，提取就在哪裡出錯
最初的提取錯誤發生在工具執行之前。以貼上內容為基礎的檢查器只會檢視你餵給它的內容，因此輸入的選擇就是整個結果的基礎。輸入端有三個問題反覆出現。
最常見的是貼上渲染後的 DOM，而非實際傳遞的 HTML 回應。許多模板透過框架在初始 HTML 載入後才注入 JSON-LD 或 Microdata。瀏覽器看得到注入的標記；爬蟲未必看得到。如果你貼上的是瀏覽器顯示的內容，你稽核的就是搜尋引擎永遠不會收到的頁面。反過來說也是個錯誤。如果你的頁面在用戶端渲染標記，卻貼上空白的傳遞 HTML，提取結果就會顯示沒有任何項目，讓你去追查模板中一個根本不存在的問題。
第二個輸入端的錯誤，是從與你部署的不同模板變體貼上內容。分類頁、標籤彙整頁和單一紀錄頁可能共用同一個版面，卻輸出不同的結構化資料。檢查其中一個變體卻部署另一個，是「在本機可運作、在正式環境失敗」這種行為的隱形來源。
第三個是部分或過大的貼上內容。在 JSON-LD 指令碼的結束標籤之前截斷模板，會抹除有效的項目。貼上整個網站的傾印則可能撞上工具的輸入大小上限而讓頁面凍結。這兩種情況都會產生描述 Google 實際上沒看到的文件的結果。
若要避免這些錯誤，請為你所部署的精確 URL 貼上傳遞的 HTML 回應。當框架在載入後注入標記時，請先比較原始回應、渲染後的 DOM 以及爬蟲可看到的輸出，再下結論。
三種被當成一種解讀的證據類別
第二類錯誤來自把檢查器的輸出當成單一訊號。輸出實際上分成三種證據類別，混為一談會導致錯誤的修復。
| 證據類別 | 代表意義 | 優先處置方式 |
|---|---|---|
| 解析錯誤 | 某個 JSON-LD 指令碼解析失敗；同一文件中的其他項目仍可能成功提取。 | 找出格式錯誤的指令碼，修正 JSON，重新提取。 |
| 缺少屬性警告 | 某個支援的 profile 找不到消費者文件標示為必要或建議的屬性。 | 在新增屬性值之前，先與連結的 profile 證據進行比對。 |
| 資訊性觀察 | 屬於工具產品範圍之外的行為（例如 RDFa 或未知類型）。 | 視為超出範圍，不要為了消除訊息而自訂規則。 |
解析錯誤很常見，因為 JSON-LD 毫不寬容。多一個尾端逗號、大括號不對稱，或字串裡少一個未跳脫的引號，就會讓整個指令碼壞掉。工具會分別回報格式錯誤的區塊，因此單一損壞的指令碼不會抹消同一文件其他地方找到的有效項目。略過那一行直接去追查屬性警告，是修復順序上的錯誤；應先修復解析錯誤，再重新提取。
缺少屬性警告的範圍比看起來更窄。Schema.org 定義了廣泛的詞彙，而搜尋產品則會針對特定體驗發布必要和建議的屬性。檢查器只在擁有已記錄規則集的位置套用明確的 profile。未知類型仍會被提取，但不會被賦予捏造出來的需求。把警告當作 Google 會拒絕該頁面的證明，正好顛倒了實際的關係：警告代表本地 profile 找不到該屬性，並不代表搜尋引擎會拒絕該標記。
資訊性觀察涵蓋工具拒絕評分的情況。RDFa 就是一例；工具僅提取 JSON-LD 與 Microdata，RDFa 落在產品範圍之外，絕不會被計為「缺少」或「無效」的結構化資料。為了「取代」RDFa 屬性而新增一個 JSON-LD 區塊，會在不知不覺中重複同一個事實，並擾亂稽核。
如何對貼上的 HTML 使用 JSON-LD 檢查器
以貼上內容為基礎的工作流程，最適合在每一步聚焦於不同的問題。結構化資料檢查器與提取工具會依下列順序執行。
- 貼上傳遞的 HTML 原始碼；若框架在載入後才水合（hydrate），則貼上受控的渲染後 DOM 匯出。
- 執行提取。所有解析都在一個分離的瀏覽器模板片段中進行，因此不會去擷取、執行來源，也不會將其送往 Lizely。
- 單獨檢視 JSON-LD 解析錯誤，與清單中的其他項目分開。格式錯誤的區塊不會抹消其他指令碼或 Microdata 中找到的有效項目。
- 分別走查 JSON-LD 項目與 Microdata 項目。JSON-LD 可包含單一物件、陣列，或含多個節點的 @graph；工具會展開這些容器，同時保留已宣告的 @type 值。Microdata 則在一般 HTML 上使用 itemscope、itemtype 與 itemprop，巢狀項目會保持巢狀，而不會被攤平成無關的字串。
- 將缺少屬性警告與連結的 profile 證據進行交叉比對。將未知類型視為「已提取」，而非「已評分」。
- 修正來源模板、重新部署，再以你所針對的搜尋功能官方工具驗證已部署的 URL（Google 功能用 Google 的複合式搜尋結果測試，之後重新檢索後再搭配 Search Console 的強化報告）。
這個順序讓每一步都可被反駁。貼上回答「來源長什麼樣子」。提取回答「存在哪些結構化資料」。警告回答「本地 profile 預期什麼」。已部署 URL 的驗證回答「搜尋引擎實際收到什麼」。把這些問題混為一談，正是稽核失去對「哪一層出錯」掌握的方式。
為什麼乾淨的提取並不保證複合式搜尋結果
在任何 JSON-LD 檢查器工作流程中，影響最大的單一錯誤，就是把綠色結果當作複合式搜尋結果的保證。工具回報的是關於貼上標記的事實。是否符合複合式搜尋結果的資格，則是另一個問題，它取決於至少四個檢查器無法檢視的層面。
| 檢查器以外的層面 | 仍可能出錯的地方 | 如何抓出問題 |
|---|---|---|
| 可見內容 | 標記所代表的內容被 CSS 隱藏、藏在未展開的分頁之後，或在使用者互動後才渲染。 | 在乾淨的瀏覽器中開啟已部署的頁面，並將渲染後的內容與提取出的屬性進行比對。 |
| 功能專屬政策 | 類型正確，但該功能受到地區、內容類別或發布者狀態的限制。 | 在依賴一份乾淨的警告清單之前，請先閱讀該功能的官方文件。 |
| 部署 | 某個建置步驟、代理或 CSP 移除了 script 標籤，或改寫了回應內容。 | 以官方工具驗證已部署的 URL，而非來源模板。 |
| 索引 | 頁面未被重新檢索、被降權，或被某條 robots 規則排除。 | 在提出重新檢索請求後，檢視 Search Console 的強化報告。 |
誠實的解讀順序是：先看解析是否有效，接著是可見內容，再來是功能政策，再來是部署，最後才是索引，依此順序。把提取結果當作最終結論，是這個錯誤最昂貴的版本，因為它會把下一層問題藏在一個綠燈背後。
修正模板勝過為了消除警告而新增欄位
最後一類錯誤會在提取看起來「差不多對」的時候出現。誘惑在於不斷新增缺少的屬性，直到警告清單縮短。這種修法往往會讓實作變得更不可信。
必要屬性的指引不能取代內容審查。工具找不到作者這種警告，是個提示代表模板沒有輸出作者，而不是提示你去捏造一個。價格缺少的警告，則是提示你要嘛把價格顯示在可見頁面上，要嘛完全省略該屬性。新增一個通用值、佔位符，或與可見頁面矛盾的數值，會產生搜尋引擎可獨立察覺的不一致。
少量但完整且真實的屬性，優於塞滿通用或捏造數值的大型物件。Schema.org 是一套詞彙，不是承諾；搜尋引擎會依據屬性值實際陳述的內容來評分頁面。一份只有三個真實屬性、沒有評分的 Recipe，會勝過一份有八個屬性、其中四個描述頁面上根本不存在內容的 Recipe。
這也是來源模板修正之所以重要的地方。檢查器檢視的是貼上的 HTML，而不會修補它。可採取行動的產出物是模板，而不是警告清單。請打開輸出 JSON-LD 區塊（或 Microdata 屬性）的模板，修正會把該屬性丟掉的那個條件，重新產生傳遞的 HTML、重新提取，最後才進一步以官方驗證工具檢查公開的 URL。
若想更仔細地了解解析錯誤與 Microdata 空白是如何並列呈現的，提取問題指南 從疑難排解的角度涵蓋了同一個工具。若想了解每種格式本身的基礎介紹，Google 的 結構化資料介紹 說明了搜尋引擎支援的格式，而 WHATWG 的 HTML Microdata 規格 則定義了檢查器所走訪的屬性行為。
如果你正在權衡選項，Canonical Tag Generator：避免這些輸入錯誤 對此有詳細說明。