當 JSON-LD 檢查工具回傳的結果看起來有誤時，修正方式幾乎總是在來源 HTML 中，而不是在擷取工具本身，因為 結構化資料檢查與擷取工具只會回報貼上的文件中已存在的內容，而它所標示出的每一個對齊錯誤項目，都會對應回標記中的特定一行。讀者經常把令人意外的擷取值當作工具的 bug，但實際上它只是忠實反映了一個真實問題:某個 script 區塊中的剖析錯誤、重複的 @type、範本從未輸出的屬性，或是 Microdata 項目在其網址上使用了錯誤的屬性。當結果看起來有誤時，能分辨它屬於上述四種情況中的哪一類，正是避免徒勞無功與在下一次貼上時取得乾淨擷取結果的差別所在。
為何擷取結果有時看起來有誤
真實頁面上的結構化資料是由範本、外掛、佈景主題與內容欄位所產生，而這些元件可能是在不同時期組裝而成，彼此之間也可能出現不一致。當這份組裝好的 HTML 被貼進檢查工具時，你所看到的清單就是所有貢獻者加總後的結果。「錯誤」的結果很少是單一瑕疵，而通常是檢查工具刻意揭露的一小組結構性問題中，某一個的可見症狀。一旦辨識出類別，修復就會變得機械化。
四個根本原因涵蓋了大多數看起來有誤的輸出:
- 無法剖析的 JSON-LD script 區塊。在嚴格 JSON 模式下，缺少逗號、未閉合的方括號或結尾多餘的逗號，會讓整個 script 失效，而不只是該錯字附近的屬性失效。
- 範本輸出了重複的項目。兩個 JSON 文件被串接進同一個 <script> 標籤，或是佈景主題加上應用程式同時寫入同一個 Product 物件，就會產生兩個互相競爭的區塊，讓下游消費者感到困惑。
- 宣告的類型含有範本從未填入的屬性。檢查工具會依據已記載的設定檔標示出缺少的欄位，但這類警告僅供參考;該屬性可能是刻意省略，也可能代表範本需要新增欄位。
- Microdata 項目使用了錯誤的屬性。連結的 href 是讀取自 href 屬性而非其文字內容，因此即使頁面呈現出正確的目的地，Microdata 的網址仍可能顯示為空白。
診斷擷取工具實際看到的內容
在進行任何修改之前，先區分你預期的內容與檢查工具實際讀到的內容。結構化資料檢查與擷取工具會在獨立於頁面的瀏覽器範本片段中剖析貼上的 HTML，絕不會擷取或執行來源頁面，並將剖析錯誤、聚焦的缺少屬性警告與參考性觀察分別回報在三個不同的區塊中。當一個看起來有誤的結果把這三種訊號混雜在一起，這通常屬於閱讀上的問題，而不是擷取上的問題。
兩個實用的檢查步驟能讓診斷回歸事實:
- 確認你貼上的是爬蟲實際接收到的回應。瀏覽器的「Inspect element」會顯示 JavaScript 執行後的 DOM，這可能與傳遞給搜尋機器人的原始 HTML 不同。如果框架在載入後才注入標記，請先比較原始回應、渲染後的 DOM 與爬蟲可見的輸出，再下結論。
- 逐一檢視每個擷取項目，而不是只看數量。檢查工具會將 @graph 節點、頂層陣列與巢狀 Microdata 展開為個別可檢視的項目，同時保留已宣告的 @type 值，因此「三個項目」的數量應對應到三個可分別檢視的區塊。
修正看起來有誤的 JSON-LD 檢查工具結果
這是核心的修復工作流程。每個步驟依序執行，每一步都會改變下一步所能確認的內容。
- 將實際傳遞的 HTML 來源或受控的渲染後 DOM 匯出檔貼進結構化資料檢查與擷取工具。不要從 JavaScript 已重寫標記的即時瀏覽器分頁貼上，因為檢查工具不會擷取或執行頁面，只能處理你所提供的內容。
- 執行擷取後，先開啟 JSON-LD 剖析錯誤區塊。格式錯誤的 JSON 區塊會被獨立回報，因此同一份文件中某個損壞的 script 並不會抹消其他位置中找到的有效項目，但該損壞的區塊在任何其他警告變得有意義之前，仍須先修復。
- 檢視擷取清單中的每個 Microdata 項目、宣告類型與屬性。確認預期的類型確實存在、範本未輸出重複項目，且特定變體中沒有缺少必要欄位。留意檢查工具保留巢狀結構而非默默攤平的巢狀 Microdata 項目。
- 對照每個支援設定檔的連結說明文件，檢視聚焦的缺少屬性警告。警告代表本地設定檔未找到對應屬性，並不代表搜尋引擎會拒絕該頁面;而一個看似奇怪的「缺少」項目，可能只是反映了該類型不在檢查工具已記載的規則集內。
- 修正產生該標記的來源範本，而不是修正擷取輸出。更正必須落到範本、外掛組態或輸出錯誤值的內容欄位上。
- 每次修改範本後重新擷取。貼上新的 HTML，確認剖析錯誤已消失，並確認屬性清單現在與頁面對訪客呈現的內容一致。
- 使用目標搜尋功能適用的官方工具驗證已部署的 URL(例如針對 Google 目標類型使用 Google 的 Rich Results Test)，並在重新擷取後檢視 Search Console 的增強功能報告，確認已部署的回應與本地擷取結果一致。
JSON-LD 與 Microdata:結果看起來有誤的不同原因
JSON-LD 與 Microdata 的失效方式不同，因此診斷路徑取決於頁面實際輸出的語法。JSON-LD 存在於 <script type="application/ld+json"> 標籤中，可以包含一個物件、一個物件陣列，或是一個含有多個節點的 @graph。檢查工具會將這些容器展開為個別項目，同時保留其已宣告的 @type 值，因此 JSON-LD「錯誤」的結果通常可追溯到語法錯誤、範本忘了展開的容器，或是 JSON 從未包含的屬性。
Microdata 則是在一般 HTML 內部使用 itemscope、itemtype 與 itemprop 屬性。檢查工具會走訪剖析後的文件，為頂層項目建構一個有界的屬性檢視，辨識透過內容屬性、連結、媒體來源屬性、日期值與文字內容所暴露的值。Microdata「錯誤」的結果通常可追溯到父元素缺少 itemscope、itemprop 放在檢查工具不會讀取其屬性的標籤上(例如頁面預期讀取 href，卻放在 data- 屬性上)，或是瀏覽器視覺上已攤平但剖析器仍保留巢狀的巢狀項目。
如果頁面同時混用兩者，請把它們當作兩份獨立的清單來處理。乾淨的 JSON-LD 區塊無法拯救損壞的 Microdata 區塊，反之亦然。
輸出看起來有誤的常見原因
下表將讀者最常回報的症狀對應到結構性原因與修正方向。此為定性對應;每個類型的精確屬性清單來自檢查工具的設定檔與連結的說明文件，而非本文。
| 結果中看到的狀況 | 可能的結構性原因 | 修正方向 |
|---|---|---|
| JSON-LD 區塊被列為剖析錯誤，其他項目仍然存在 | 某個 script 區塊中的結尾多餘逗號、缺少方括號或多餘字元 | 在來源範本中修復 JSON;重新擷取 |
| 出現兩個 Product 或 Article 項目，但你預期只有一個 | 佈景主題與應用程式同時將相同類型輸出到同一個 script | 移除其中一個輸出者，或將兩者包進 @graph |
| 已擷取類型，但沒有套用任何屬性設定檔 | 不熟悉的 Schema.org 類型，不在已記載的設定檔內 | 確認該類型是否為刻意使用;對照目標搜尋功能進行檢視 |
| Microdata 網址顯示為空白 | itemprop 放在錯誤的屬性或子元素上 | 將 itemprop 移至應讀取其 href 或 src 的元素 |
| 必要屬性被標示為缺少，即使欄位已填入 | 範本將值輸出到錯誤的屬性名稱 | 在範本中重新命名屬性以符合說明文件記載的名稱 |
| 項目數量與你貼上的內容不符 | @graph 或陣列中含有多個節點 | 確認每個節點都是刻意存在;清單中保留巢狀項目的巢狀結構 |
當修正超出範本所能處理的範圍
有時看起來有誤的結果根本不是結構性瑕疵。檢查工具刻意將剖析錯誤、聚焦的屬性缺口與參考性觀察分開回報，正是為了讓這種區別得以看見:有效的 JSON 可能描述了不正確、隱藏或不相關的內容;看似完整的物件仍可能違反搜尋政策、與可見頁面不一致、使用了不支援的功能，或無法通過部署測試。如果清單是乾淨的，但頁面仍未獲得你預期的複合式搜尋結果，那問題在於內容或政策，而不是標記。必要屬性的指引無法取代內容審查;為了消除警告而新增欄位，反而可能讓實作更不值得信賴。較少但完整且真實的屬性，優於塞滿籠統或捏造值的大型物件。
修正之後:透過官方工具進行驗證
乾淨的本地擷取只是預檢，並非最終裁決。複合式呈現是否以及何時出現，最終由搜尋引擎決定，任何本地檢查工具都無法保證索引、排名或複合式搜尋結果。一旦來源範本的修改部署完成，請透過你實際目標功能適用的官方驗證工具跑過公開的 URL——針對 Google 目標類型使用 Google 的 Rich Results Test——並在重新擷取後檢視 Search Console 的增強功能報告，確認已部署的回應與本地擷取結果一致。如果已部署的回應與貼上的來源不同，則以已部署的回應為準，並應使用該已部署 HTML 的全新貼上內容重新執行本地擷取，再下進一步的結論。
想進一步了解，請參閱 如何開始使用 JSON-LD 結構化資料檢查工具。
想進一步了解，請參閱 驗證你的 JSON-LD 檢查工具擷取資料是否正確。