疑難排解 JSON-LD 檢查器擷取問題時，代表在變更任何範本之前，必須先隔離失敗的環節——是 JSON-LD 解析、Microdata 走查，還是設定檔警告。大多數擷取投訴都屬於少數幾種模式：解析器仍會拒絕一個看起來有效的 JSON-LD 區塊、一個 Microdata 項目從未出現在輸出中、一個不熟悉的 Schema.org 類型出現時卻沒有任何必要屬性的回饋，或是一個看起來權威但無法預測 Google 行為的警告。結構化資料檢查器與擷取工具會將這些環節分開，讓每個問題對應到不同的第一個問題。解析錯誤指向指令碼區塊本身。Microdata 缺口指向 HTML 樹狀結構和屬性擺放位置。設定檔警告指向消費方的說明文件，而非標記的語法有效性。乾淨的本機結果只是關於所貼上文件的證據——並非關於搜尋結果呈現的承諾——而失敗的本機結果則是關於所貼上標記的證據，仍可能與爬蟲接收到的實際線上頁面不同。
看似檢查器問題的常見症狀
在著手修正之前，先精準描述症狀會很有幫助。同樣的抱怨——「檢查器壞了」——通常隱藏著四種可辨識的失敗形態之一，而每種形態都屬於擷取流程中的不同環節。
第一種形態是在一個大致合理的 JSON-LD 區塊中回報的解析錯誤，常見原因包括結尾多了一個逗號、未加引號的鍵，或是在指令碼結尾處多出一個字元。第二種形態是缺少項目：頁面明顯包含 JSON-LD 指令碼或 Microdata 屬性，但擷取結果卻對該區塊回傳空。第三種形態是已出現的項目中某個屬性值為空或空白，這通常代表使用了錯誤的屬性（例如，把 href 值放在非連結元素上）。第四種形態是檢查器對你認為已完整填寫的類型標示「缺少必要屬性」的警告。
| 你看到的症狀 | 可能的失敗環節 | 第一個檢查項目 |
|---|---|---|
| 在你認為有效的 JSON-LD 區塊上出現「Parse error」 | JSON-LD 解析 | 重新執行擷取；單獨貼上指令碼以進行隔離 |
| 從你已標記的頁面中擷取到零個項目 | Microdata 走查或指令碼擺放位置 | 確認 itemscope 或 itemtype，或指令碼在文件中的位置 |
| 項目有出現但列出的屬性都是空白 | Microdata 屬性對應 | 檢查 itemprop 拼字與上層範圍 |
| 出現關於缺少「必要」屬性的警告 | 設定檔規則，並非語法問題 | 對照該功能的說明文件確認類型 |
| 本機檢查器與線上頁面結果不一致 | 輸入內容不符 | 比對所貼上的 HTML 與爬蟲可見的輸出 |
辨識出哪一列描述了你的症狀，就能決定下一步動作。如果症狀落在第一列，修正點在指令碼文字本身。如果落在第二或第三列，修正點在 HTML 樹狀結構。如果落在第四列，修正點在消費方的說明文件，而非你的標記。
疑難排解 JSON-LD 檢查器擷取問題
一個簡短的診斷流程能讓工作範圍保持明確。每一步只回答一個問題，而這些答案會逐步縮小範圍，直到原因顯而易見。
- 確認你貼上的內容。檢查器是根據你提供的 HTML 或受控的 DOM 匯出來運作，而非根據線上 URL。如果框架在載入後才注入標記，渲染後的 DOM 可能會與伺服器原本的回應不同。在解讀任何結果之前，請先決定你打算稽核的是哪一個版本。
- 區分解析錯誤與擷取結果。格式錯誤的 JSON-LD 區塊會被單獨回報，因此一個損壞的指令碼並不會抹除在其他地方找到的有效項目。在決定要修正哪些內容之前，請分別記下每一個解析錯誤與每一個成功擷取到的項目。
- 針對每個缺少的項目，判斷它屬於 JSON-LD 還是 Microdata。JSON-LD 項目會消失，通常是因為指令碼解析失敗，或根本不在所貼上的文件中。Microdata 項目會消失，則通常是因為走查器從未走到那些元素——常見原因是 itemscope 或 itemtype 拼字錯誤，或是標記位於所貼上的片段之外。
- 針對每個空白屬性，判斷預期應使用哪個屬性。Microdata 透過 content 屬性、連結、媒體來源、日期值或文字內容來公開其值。如果值放錯了屬性，該屬性在擷取檢視中就會顯示為空。
- 針對每個設定檔警告，判斷它適用於哪一個消費方。檢查器只套用明確、有書面記載的設定檔。出現警告代表本機設定檔在所貼上的標記中找不到該屬性；這並不能證明搜尋引擎會拒絕該頁面。
- 修正範本後重新執行。請編輯來源範本，而非單一頁面。重新擷取，直到解析錯誤消失、所有預期的項目都出現，並且警告都已解決或理解其原因。
JSON-LD 解析錯誤及其真正意涵
解析錯誤訊息會指向指令碼中的某個位置。把它讀成「JSON 在第 N 個字元處有誤」會比讀成「檢查器壞了」更有用。特定模式會在範本中反覆出現，而每種模式都有其典型原因。
| 模式 | 典型原因 | 應檢查的位置 |
|---|---|---|
| Unexpected token（非預期的符號） | 結尾多一個逗號、未加引號的鍵，或多餘的字元 | 錯誤位置前方的最後一個屬性 |
| Unterminated string（未結束的字串） | 值內部缺少結尾引號 | 從 CMS 複製的長網址或描述 |
| Unexpected end of JSON（非預期的 JSON 結尾） | 缺少結尾的大括號或中括號 | 整體大括號與中括號的平衡 |
| Invalid escape（無效的跳脫） | 值中出現錯誤的反斜線序列 | 網址與富文字描述 |
JSON-LD 可以包含一個物件、一個物件陣列，或是一個含多個節點的 @graph。檢查器會將這些容器展開為個別項目，同時保留每個宣告的 @type 與可見的屬性，因此指令碼的結構本身並不會導致擷取失敗。然而，格式錯誤的區塊會被單獨回報，且絕不會被悄悄與其他有效的區塊合併。
當一個指令碼看似正確卻沒有回傳任何項目時，最常見的原因是該指令碼由框架在頁面載入後才載入，並未包含在所貼上的片段中。次常見的原因則是某組值在壓縮過程中被周圍的 HTML 引擎移除了。這兩種情況的修正方式都相同：比對伺服器原始回應、渲染後的 DOM，以及爬蟲可見的輸出，然後貼上包含你預期要稽核之標記的那個版本。
消失或顯示空值的 Microdata 項目
Microdata 在一般 HTML 中使用 itemscope、itemtype 與 itemprop 屬性。檢查器會走查已解析的文件，並為頂層項目建立一個有界限的屬性檢視，這代表缺少的項目通常來自於範圍錯誤，而非解析器錯誤。
首先要確認的是，itemscope 確實位於你以為的那個元素上。屬性拼字錯誤（itemscopee、item-scope、itemscope="false"）會讓該元素靜默地變成普通標籤。其次要確認 itemtype 指向一個有效的 Schema.org 網址；無法連線或拼字錯誤的類型不會中斷擷取，但會讓結果中的項目無法對應到任何有書面記載的設定檔。第三要確認的是巢狀項目仍維持可見的巢狀結構：位於子項目 itemscope 中的子項目 itemprop，不應被壓平合併到父項目的屬性清單中。
空白值通常代表資料被放在錯誤的屬性上。把產品網址放在 data-* 屬性、把圖片網址放在 alt 文字、或把日期放在沒有機器可讀屬性的 span 中，在擷取檢視中都會顯示為空白。確認是哪個屬性公開該值，再讓 itemprop 與該屬性對齊，即為標準修正方式。如需進一步了解在套用這些修正後，應如何解讀擷取到的屬性清單，請參閱擷取後如何解讀 JSON-LD 檢查器結果。
本機檢查器看似正常，但仍有問題時
乾淨的本機結果是關於所貼上文件的陳述，而非關於該頁面的陳述。以下三種不一致的情況，常能用來解釋「檢查器說沒問題，但線上頁面表現仍與預期不符」。
第一種不一致發生在伺服器回應與渲染後的 DOM 之間。直接貼上的靜態 HTML 檔案可能包含 JSON-LD；但在瀏覽器中渲染的單頁應用程式，則可能因為標記是在載入後才注入而不含 JSON-LD。第二種不一致發生在瀏覽器與爬蟲之間。Cloudflare 驗證、依地理位置的重新導向、依 IP 區分的版本，以及語言選擇器，都可能改變爬蟲接收到的回應。第三種不一致發生在消費方的設定檔與頁面實際內容之間。檢查器僅在有書面記載規則集的地方套用明確、可檢視的設定檔；未知的類型仍會被擷取，但不會被賦予憑空捏造的需求。
務實的結論是：乾淨的本機執行能賦予你對已部署的 URL 執行官方測試的資格，但這本身並不能取代該步驟。針對 Google 的複合式搜尋結果功能，官方的結構化資料說明描述了每項功能接受哪些格式與屬性；WHATWG 的 HTML Microdata 規格則定義了解析器如何解讀 Microdata 屬性。
疑難排解之後：驗證已部署的 URL
一旦本機檢查器回報的標記符合你的預期——解析錯誤已解決、預期的項目都已出現、警告都已理解——下一步就是使用你所實際針對的搜尋功能之官方工具，來驗證已部署的 URL。當類型針對的是 Google 的功能時，適合使用 Google 的複合式搜尋結果測試。對於超出該範圍的功能，則適合參考該消費方自家的驗證工具或說明文件。
當變更正式上線後，Search Console 的強化項目報告、重新抓取請求，以及具代表性的範本測試，可用來確認長期行為。搜尋引擎會決定是否以及何時顯示強化後的呈現方式，因此沒有任何本機檢查器能保證索引、排名或複合式搜尋結果的出現。本機檢查器的職責範圍比那更窄，也更有用：它根據所貼上文件的證據，告訴你標記是否內部一致，並符合你正嘗試滿足的設定檔。