用Claude Code做JavaScript SEO：修改範本前先建立證據資料夾

JavaScript SEO 真正危險的地方，不是執行檢查清單，而是因為某項檢查聽起來合理，就直接修改多個頁面共用的範本。分類頁面在你的瀏覽器裡可能看起來完全正常，但連結其實依賴點擊事件、實用內容很晚才出現，或 canonical 與 HTTP 回應傳達不同訊號。錯誤的「SEO 修正」可能破壞導覽、分析追蹤、無障礙體驗，甚至影響所有使用該元件的頁面。

Claude Code 最有價值的用法，是把一個真實的頁面觀察，連到最小的相關程式碼路徑、可供審查的 diff，以及一組測試。它不該從重寫框架或直接部署修補開始。

完成這套流程後，你會得到： 一個儲存庫證據資料夾、一條本機調查規則、一份從單一頁面症狀連到可能相關檔案的地圖、一份經負責人核准的實作簡報，以及一筆完成測試的變更紀錄。這裡的「完成」不代表 Google 已重新檢索頁面，也不代表排名已經提升。

第一部分：開啟儲存庫之前，先理解JavaScript SEO

頁面依賴JavaScript時，會有什麼不同

Web 伺服器會對 URL 回傳回應。這份回應可能已包含頁面的主要內容，也可能只包含一個外殼，要求瀏覽器執行指令碼並再請求資料。之後，瀏覽器才建立最終的頁面狀態。

搜尋系統也必須發現 URL、取得回應、處理獲准的資源，並理解最後形成的頁面。使用現代 JavaScript 本身不會自動造成 SEO 問題。問題通常出現在重要步驟不可靠，或頁面不同層次講述不同故事的時候。

對初學者來說，可以使用這個模型：

發現 URL
  -> 收到伺服器回應
  -> 處理 HTML 與資源
  -> JavaScript 與資料請求完成
  -> 解讀內容、連結與頁面訊號
  -> 搜尋系統決定是否以及如何索引該 URL

每個箭頭都可能失敗，而儲存庫只包含部分證據。程式碼可以顯示元件原本打算如何運作，卻不能單獨告訴你 Google 索引了哪個 URL、昨天某次正式環境請求是否失敗，或特定裝置上的使用者實際經歷了什麼。

不要把「JavaScript」當成單一問題，請檢查六種頁面行為

1. URL回傳預期的狀態

正常頁面通常回傳 200。已移除的頁面應傳達有意義的 not found 或 gone 狀態。重新導向應抵達預期的最終 URL。用戶端重新導向可能比較慢，也可能掩蓋在 HTTP 層更容易看出的錯誤。

2. 主要內容可以取得

定義頁面的文字與項目，應出現在相關回應或完成轉譯的狀態中。請記錄內容是否需要指令碼、資料請求、捲動、點擊、登入或其他條件才會出現。內容不在原始 HTML 中是一項觀察，不等於頁面一定無法被索引。

3. 重要目的地是實際連結

搜尋系統通常透過標準連結發現目的地。只靠 onClick、按鈕或片段導覽的卡片，在視覺上可能可以使用，卻可能提供較弱的 URL 發現路徑。適當修正也許是加入真正的連結，但必須保留鍵盤操作、分析追蹤、樣式與應用程式路由。

4. canonical、robots與網站地圖訊號一致

請確認請求的 URL、canonical 目標、robots 指示、內部連結和網站地圖項目都指向同一個偏好頁面。canonical 是提示，不能取代乾淨的 URL 處理，也不應指向無關頁面。

5. 延遲載入與無限捲動具有可抵達狀態

延遲載入可以改善效能，但重要內容不應依賴任意互動。無限捲動通常應提供穩定的分頁 URL，或通往更深層項目的其他可檢索路徑。實作方式取決於網站，因此提出變更前要先檢查既有路由與資料模型。

6. 中繼資料與結構化資料符合可見頁面

title、canonical、robots 指示與結構化資料可能在 JavaScript 執行後才產生。它們應準確且一致地描述可見內容。結構化資料有助於解讀頁面，但不保證複合式搜尋結果或排名。

分開四種證據

使用儲存庫代理時，這種區分格外重要。Claude Code 很擅長追蹤元件，但離程式碼越近，越容易把看似合理的機制誤當成已確認的原因。

寫下一個以證據為基礎的症狀

不要從「Google 無法轉譯我們的網站」開始。這句話包含了你可能尚未證明的結論。請使用更精確的敘述：

在提供的分類頁面擷取資料中，商品名稱會在轉譯後出現，但轉譯後 DOM 的商品卡片不含標準目的地連結。搜尋引擎索引狀態未知。

這讓 Claude Code 有一個具體項目可以追查，也把調查限制在負責分類卡片和導覽的程式碼，而不是應用程式裡所有轉譯決策。

第二部分：建立從證據走向已審查diff的Claude Code工作流程

準備儲存庫證據資料夾

選擇一個不屬於應用程式原始碼的位置。沿用儲存庫既有的產出物或報告慣例；若沒有慣例，可以從以下結構開始：

reports/javascript-seo/
  collection-page-links/
    page-story.md
    response-notes.md
    rendered-notes.md
    search-evidence.md
    decision.md

資料夾應回答四個問題：正在調查哪個頁面、觀察到什麼、哪些資料仍無法取得，以及負責人做了什麼決定。若擷取內容與匯出資料不應進入版本控制，請將它們設為忽略項目。

絕對不要在資料夾中放入 Cookie、API 權杖、密碼、私人客戶資料或未限制的匯出檔。把證據交給任何工具之前，都要先遮蔽私人 URL 與使用者資訊。

在負責人核准實作簡報之前，請讓唯讀調查紀錄與原始碼保持分離。

在第一個提示詞之前加入儲存庫規則

把政策放進專案既有的 Claude Code 指引位置，例如相關的 CLAUDE.md 或既有 .claude 規則。若專案已經有指示系統，就不要另建第二套。

## JavaScript SEO 調查政策

- JavaScript SEO 工作從唯讀證據蒐集開始。
- 調查筆記只能存放在核准的證據目錄。
- 分開觀察事實、可能機制、未知事項與負責人決策。
- 在具名實作簡報獲得人工核准前，不得編輯原始碼、路由、robots 規則、
  內容、CMS 資料、部署檔案或 CI。
- 除非提供經授權的匯出資料，否則將 Search Console、檢索紀錄、
  正式環境指標與索引狀態視為無法取得。
- 絕不揭露機密、Cookie、權杖、私人 URL 或客戶資料。
- 核准後執行範圍最小的變更、顯示 diff、執行約定測試，並說明回復條件。
  除非另行授權，否則不得部署。

這項規則能提供持續指引，但本身不是強制執行層。仍應配合專案適用的儲存庫權限、分支保護、命令核准與程式碼審查。

建立頁面故事

加入簡短的 page-story.md，讓儲存庫調查始終連結到頁面的用途。

## 頁面
https://example.com/collections/shoes

## 訪客工作
比較現有鞋款並開啟商品頁面。

## 必要頁面元素
- 分類標題
- 商品名稱與價格
- 穩定的商品目的地
- 一致的 title、canonical、robots 指示與狀態

## 觀察到的症狀
提供的轉譯 DOM 中有商品卡片，但沒有標準商品連結。

## 可用證據
- 儲存的回應筆記
- 轉譯後 DOM 摘錄
- 儲存庫簽出內容

## 無法取得的證據
- Google URL 檢查
- 伺服器紀錄
- 正式環境欄位指標

## 禁止動作
調查期間不得編輯原始碼、部署、變更 CMS、提交 URL 或傳送外部訊息。

頁面故事可以防止調查偏離成一般性的程式碼審查。

請Claude Code繪製程式碼地圖，而不是立即修正

第一個提示詞請使用唯讀模式：

以唯讀模式調查一個 JavaScript SEO 症狀。

頁面故事：reports/javascript-seo/collection-page-links/page-story.md
證據資料夾：reports/javascript-seo/collection-page-links/

閱讀儲存庫指引。只檢查可能負責所述頁面與症狀的程式碼路徑。請回傳：
1. 已確認證據摘要
2. 可能相關的路由、範本、元件與資料路徑，以及判斷理由
3. 不確定之處與缺少的資料
4. 最小的實作選項
5. 驗收檢查與回復條件

不要編輯檔案、安裝套件、部署、呼叫可寫入 API，也不要聲稱 Google 已索引或
未索引該頁面。完成調查簡報後停止。

預期輸出： 一份從頁面路由連到範本、元件、導覽行為和相關測試的地圖。品質檢查： 每個候選檔案都要連結到觀察到的症狀。復原方式： 如果答案提出框架遷移，請改問可逆、範本層級的最小選項及其證據。

像開發人員一樣審查程式碼地圖

實用的程式碼地圖會說明資料和標記如何抵達頁面。對分類卡片問題來說，它可能找出：

• 路由或頁面進入點
• 分類範本
• 卡片元件
• 建立商品目的地的函式
• 導覽與分析事件處理器
• 現有的元件、無障礙或端對端測試

它也應列出未知事項。也許卡片元件支援 href，但範本沒有傳入；也許外層容器是為了避免巢狀連結；也許目的地來自在初始回應時尚未取得的資料。這些是不同機制，需要不同修正。

使用這張表審查：

把地圖轉成實作簡報

在任何編輯開始前，負責人應核准一份包含以下內容的文件：

Finding（發現）：[一個已觀察條件]
Evidence（證據）：[檔案或擷取內容]
Affected page family（受影響頁面群）：[已確認範圍]
Candidate mechanism（候選機制）：[程式碼路徑與不確定性]
Approved action（核准動作）：[一個有界線的變更]
Behavior to preserve（要保留的行為）：[導覽、無障礙、分析、樣式、路由]
Acceptance checks（驗收檢查）：[清單]
Rollback condition（回復條件）：[清單]
Owner（負責人）：[姓名或角色]
Status（狀態）：APPROVED FOR LOCAL IMPLEMENTATION / NOT APPROVED

「加入可檢索連結」仍然太寬泛。更好的核准動作會說明元件和預期行為，同時讓程式碼負責人選擇符合既有應用程式的有效標記。

執行一次受限制的編輯

核准後請開始新的提示詞。不要把廣泛調查的上下文當成已授權變更。

只實作下列文件記錄的核准動作：
reports/javascript-seo/collection-page-links/decision.md

編輯前，重述受影響檔案、要保留的行為、驗收檢查、禁止動作與回復條件。

執行最小且完整的變更。不要重構無關程式碼、變更相依套件、修改部署設定、
編輯 CMS 內容或部署。

編輯後：
- 顯示完整 diff
- 只執行已核准的本機檢查
- 回報失敗但不要擴大範圍
- 把結果更新到 decision.md

若儲存庫證據與核准的機制矛盾，請停止並回傳修訂後的簡報。

只有在受影響範本、審查關卡、預覽檢查與回復路徑都清楚時，交接才算完成。

相信說明之前，先檢查diff

把 diff 當作主要變更紀錄來閱讀。請確認它：

• 只碰到預期檔案
• 保留必要的事件處理與分析追蹤
• 沒有加入無效的巢狀互動元素
• 保留鍵盤與螢幕閱讀器行為
• 產生穩定、正確的目的地
• 新增或更新相關測試
• 沒有暗中變更 robots、canonical、重新導向或無關中繼資料

再流暢的摘要，也不能彌補範圍過大的 diff。

按照訪客與檢索器遇到頁面的順序進行驗證

本機與功能行為

建置受影響區域並測試訪客工作。使用滑鼠和鍵盤都能開啟目的地嗎？用戶端路由仍能運作嗎？分析追蹤需求有保留嗎？資料缺少時元件是否仍能正確處理？

回應訊號

檢查預期回應或預覽。確認狀態、重新導向行為、title、canonical、robots 指示，以及預期出現在回應裡的主要內容。不要把「檢視原始碼」當成完整 SEO 判決。

轉譯輸出

確認最終 DOM 含有預期內容與一般目的地。測試代表頁面，也在適用時測試空白狀態、錯誤狀態或資料無法取得的狀態。

經授權的搜尋證據

如果團隊有 URL 檢查、檢索、紀錄或 Search Console 證據，請另行記錄並附日期。本機預覽無法證明 Google 已重新檢索或索引頁面。搜尋資料可能需要時間才會變化，而且任何實作都不保證排名。

回復與紀錄

將核准簡報、最終 diff、測試輸出、預覽參照、日期與負責人決定放在一起。若應保留的行為失敗、範圍意外擴大，或預覽不再符合頁面故事，請依約定方式回復。

三個調查範例

沒有穩定連結的可點擊卡片

觀察： 卡片文字可見，但轉譯擷取顯示導覽綁在容器上，而不是一般目的地連結。儲存庫問題： 哪個元件負責主要目的地，並如何保留分析追蹤與無障礙行為？可能的最小變更： 為主要動作加入適當的標準連結。不要假設： 卡片內每個位置都應變成巢狀連結。

沒有深層URL路徑的無限捲動

觀察： 捲動後出現更多項目，但提供的證據沒有通往後續群組的穩定頁面路徑。儲存庫問題： 資料層是否已支援可對應至 URL 的頁碼或游標？可能的最小變更： 保留漸進增強，同時公開可檢索分頁。不要假設： 必須替換整個介面。

用戶端轉譯的not found頁面回傳200

觀察： 無法取得的商品在轉譯後顯示「not found」，但回應擷取內容報告 200。儲存庫問題： 系統在哪裡得知路由不可用，伺服器或框架能否回傳有意義的狀態？可能的最小變更： 在適當的路由邊界處理缺少狀態。不要假設： 只修改可見文案就能解決回應問題。

常見錯誤

要求Claude Code稽核整個網站

輸出會變得寬泛而難以驗證。從一個代表 URL 與一則頁面故事開始；只有同一機制在更多頁面得到確認後，才擴大範圍。

把CLAUDE.md當作安全控制

它是指引，不是獨立權限系統。請繼續使用命令核准、儲存庫權限與人工審查。

把證據檔案混入產品提交

擷取內容與匯出資料可能包含私人資訊或製造雜亂 diff。把它們放在核准且忽略的目錄，只提交刻意進行的程式碼與測試變更。

立即用排名衡量成功

先驗證技術目標，之後再使用經授權的檢索與搜尋資料。排名也受到關聯性、競爭、內容品質、連結及許多其他因素影響。

因為測試通過而忽略錯誤的頁面狀態

元件測試可能通過，但正式環境路由仍收到不同資料、中繼資料或狀態處理。至少包含一項接近真實訪客路徑的路由層級或預覽檢查。如果頁面有篩選器、分頁、無法取得的商品或多語版本，請說明核准變更涵蓋哪些狀態，哪些狀態不在本次範圍。

未檢查範圍就編輯共用元件

分類卡片也可能出現在搜尋、推薦、購物車或帳戶畫面。變更前，請 Claude Code 找出元件的使用位置，並判斷建議標記是否影響這些情境。如果答案擴大範圍，就把新簡報交回負責人，不要讓小修正悄悄變成重新設計。

從頭到尾完成第一個實際案例

假設頁面故事說訪客要比較商品並開啟詳情。證據資料夾有一段轉譯後 DOM，顯示商品名稱，但沒有一般目的地連結。Claude Code 讀取專案指引，把路由連到分類範本，再連到可重複使用的卡片元件和導覽事件處理器。它也報告該元件與推薦列共用，因此範圍還不確定。

真正有用的成果不是立即修補。負責人現在可以在兩個有界線的下一步中選擇：檢查元件在兩個情境下的使用方式，或建立一個提供有效主要目的地的分類專用包裝元件。負責人做出選擇後，實作提示詞要指定受影響檔案、必要測試、應保留的分析行為與回復條件。

修補完成後，團隊檢查轉譯後的分類頁面，以鍵盤導覽開啟目的地，查看路由回應與 canonical，並確認推薦列仍按照預期運作。最後，決策紀錄只寫入實際測試的內容，不聲稱搜尋引擎已重新處理所有商品 URL。

常見問題

Claude Code可以同時檢查線上網站與儲存庫嗎？

只有在所需工具與存取權可用且獲得授權時才可以。請分別標記線上頁面證據、儲存庫證據與搜尋平台證據。

CLAUDE.md檔案能阻止Claude Code編輯嗎？

它提供持續的專案指引，但本身不是強制機制。請使用環境的實際權限與審查控制。

每個JavaScript SEO問題都需要伺服器端轉譯嗎？

不需要。穩定連結、正確狀態、一致的中繼資料、可用的資料路徑或小型元件變更，都可能是適當解法。請先診斷。

應該讓Claude Code部署核准的修補嗎？

除非部署是另一項已授權的動作，並具有負責人、測試與回復計畫，否則不應部署。本機實作核准不等於正式環境發布核准。

初學者應該先調查什麼？

選擇一個高價值頁面和一個可見症狀，例如缺少標準連結或回應狀態錯誤。要求變更程式碼之前，先建立證據資料夾。

作者：Julian Mercer，Auspia 擁有 14 年經驗的技術 SEO 實務工作者，專注於可檢索性、轉譯、網站架構，以及讓 AI 容易讀取內容的技術基礎。