Skip to content
OriginalPhase Ops Handbook

Nuxt SEO Engineering Agent｜完整工作流

這份文件定義 Nuxt SEO 工程 Agent 的完整工作流，讓 Agent 能穩定檢查、建立、修復 Nuxt 專案的技術 SEO 底座。人類專注在內容策略與內容產製。

修復模式（fix-p0 / content-enable）另見 SEO 修復 Agent。

Agent 任務定義

Agent 優先處理：

  • production canonical domain 是否一致
  • sitemap / robots 是否可被 Googlebot 抓取
  • sitemap 是否只包含可索引頁
  • SSR raw HTML 是否有 head metadata 與主要內容
  • i18n canonical / hreflang 是否和實際路由一致
  • Nuxt Content 公開內容頁是否能直接貼 URL 進入並被 SSR 找到
  • PWA offline fallback 是否會攔截公開 SEO 頁

Agent 不應優先處理：文案潤飾、大規模 UI 重構、核心產品互動流程重寫。

五種模式

模式可否改程式用途預期輸出
audit-only不可全站 Technical SEO 掃描Markdown audit report
bootstrap可新專案建立 SEO 工程框架修改摘要、驗證結果、待設定 env
fix-p0可，小範圍修 Google 無法正常抓取的問題修改摘要、build 結果、GSC 操作
content-enable可，中範圍讓內容頁可被索引修改摘要、欄位需求、驗證結果
post-deploy-validate不改或只改報告部署後檢查 production 真實狀態curl 結果與結論

模式選擇規則

  • 「完整 audit」「先不要改」→ audit-only
  • 「建立 SEO 框架」「新專案套 SOP」→ bootstrap
  • 「修 sitemap」「GSC 抓不到」「noindex 矛盾」→ fix-p0
  • 「新增內容頁 SEO」「讓文章進 sitemap」→ content-enable
  • 貼 production curl / GSC 結果 → post-deploy-validate

全模式共通規則

  • 先讀現有架構，再提出或執行修改。
  • 不要重構與 SEO 無關的功能。
  • 不要改動付款、訂閱、webhook、會員資料流程。
  • 不要讓 sitemap 包含 noindex 頁。
  • 不要讓 canonical、sitemap、OG URL、JSON-LD 混用 www / non-www。
  • 不要產生不存在的 hreflang URL。
  • 不要用瀏覽器渲染結果取代 raw SSR HTML 檢查。
  • 修完要跑驗證指令。

必查的專案檔案

開始任何模式前，先掃描：

nuxt.config.ts
app.vue
layouts/**/*
pages/**/*
composables/**/*
public/robots.txt
public/sitemap.xml
server/routes/**/*
server/api/**/*
content.config.ts
content/**/*
i18n/**/*
locales/**/*
package.json

必查關鍵字

site.url / siteUrl / NUXT_PUBLIC_SITE_URL / canonical / hreflang
robots / sitemap / noindex / nofollow / og:url / og:locale
JSON-LD / schema / queryCollection / path / slug
updatedAt / publishedAt / draft / private / disabled
navigateFallback / offline / routeRules / redirect

audit-only 模式

Prompt

Nuxt Technical SEO Audit

全面掃描，不修改程式 Codex

請針對 Nuxt 專案執行 Technical SEO Audit，先不要修改程式。

請掃描 nuxt.config.ts、app.vue、layouts、pages、composables、server routes、sitemap routes、public/robots.txt、i18n 設定、package.json。

請確認：

  1. site.url / runtimeConfig.public.siteUrl / NUXT_PUBLIC_SITE_URL 是否一致使用 production canonical domain。
  2. canonical、OG URL、Twitter URL、JSON-LD、sitemap 是否混用 www / non-www 或 http / https。
  3. robots.txt production 是否允許抓取，且 sitemap URL 正確。
  4. sitemap index 與 child sitemap 是否可 200 XML 取得。
  5. sitemap 是否包含 noindex、付款、會員、offline、API、callback 頁。
  6. Nuxt Content 公開頁是否進 sitemap，draft / private 是否排除。
  7. trailing slash 策略是否一致，sitemap URL 是否回 3xx。
  8. i18n 實際路由、canonical、hreflang、x-default 是否一致。
  9. HTML head 是否有 title、description、canonical、hreflang、html lang、OG、Twitter、robots meta。
  10. PWA workbox navigateFallback 是否會讓公開 SEO 頁直接進站落到 /offline。
  11. 動態內容頁直接貼 URL 時，SSR HTML 是否真的有內容，不是「找不到」或 loading shell。
  12. Googlebot UA curl 是否被 challenge、403、HTML fallback 或錯誤 Content-Type 影響。

請輸出：

  • Executive Summary：最可能的 3 個根因
  • P0 / P1 / P2 問題清單（含影響、根因、建議）
  • Sitemap / Robots / Metadata / i18n / PWA / Cloudflare 各章節檢查
  • Indexability Matrix
  • 修正計畫
  • 修正後驗證指令

bootstrap 模式

Prompt

Nuxt SEO Bootstrap

為新專案建立 SEO 工程底座 Codex

請為這個 Nuxt 專案建立可維護的 SEO 工程底座。

請設定：

  1. canonical site URL（site.url + runtimeConfig.public.siteUrl）
  2. site.name / site.description / defaultLocale / trailingSlash
  3. robots rules（允許公開頁、封鎖 api / account / payment 等）
  4. sitemap exclude（offline / api / account / payment / auth / login）
  5. 公開 content 的 sitemap sources
  6. canonical / hreflang composable
  7. JSON-LD composable
  8. noindex pages meta
  9. 若有 PWA，設定 navigateFallbackDenylist
  10. 建立 verify:seo script

可修改的檔案：nuxt.config.ts、app.vue / default layout、SEO composables、sitemap utilities、robots config、content schema、docs。

Exit criteria：

  • npm run build 通過
  • sitemap 能生成
  • robots 能生成
  • raw SSR HTML 有基本 head metadata
  • 文件列出 production env 必填項（NUXT_PUBLIC_SITE_URL）

post-deploy-validate 模式

Prompt

Nuxt SEO Post-Deploy Validation

部署後驗證 production 真實行為 Codex

請驗證 production 真實行為，不依賴本機推測。

Header 檢查：

Terminal window
curl -I https://example.com/
curl -I https://www.example.com/
curl -I https://www.example.com/robots.txt
curl -I https://www.example.com/sitemap_index.xml
curl -I https://www.example.com/__sitemap__/zh-TW.xml
curl -A "Googlebot" -I https://www.example.com/__sitemap__/zh-TW.xml

Body 檢查：

Terminal window
curl -L https://www.example.com/robots.txt
curl -L https://www.example.com/sitemap_index.xml
curl -L https://www.example.com/__sitemap__/zh-TW.xml | head -80

Pass criteria：

  • non-www → 301/308 → canonical domain
  • canonical domain → 200
  • robots.txt → 200
  • sitemap index → 200 XML
  • child sitemap → 200 XML
  • Googlebot UA → 200，不被 challenge
  • sitemap loc 全部 canonical domain
  • sitemap 不含 noindex / private 路由
  • content URLs 直接 curl 有主要內容

請輸出：已達標 / 未達標 / 風險 / GSC 建議操作。

SEO 驗證 Script 需求

建議建立 scripts/verify-seo.mjs，至少檢查：

  • sitemap XML 可 parse
  • sitemap 不含 /offline、/payment、/account、/history、/login、/register
  • sitemap 包含公開內容頁
  • sitemap URL 使用 canonical domain
  • sitemap URL 使用 final trailing slash
  • /、/ja、/en raw HTML 有基本 head
  • JSON-LD 不含 non-canonical domain
{
  "scripts": {
    "verify:seo": "node scripts/verify-seo.mjs"
  }
}

Agent 回覆格式

每次執行完，最後回覆必須包含：

## 模式
## 做了什麼
## 修改檔案
## 驗證結果
## 尚未處理
## 使用者下一步

若沒有修改程式，明確說「未修改程式」。若 build 沒成功，明確說原因。若需要部署後才能確認，列出 production 驗證指令。

完成標準

Checklist

Nuxt SEO Engineering Agent 工作流

P1

  • 使用者指定模式（或預設 audit-only）
  • 先讀架構再執行
  • 不修改與 SEO 無關的功能
  • 報告包含 P0 / P1 / P2 分級
  • 每個問題有證據與驗證方式
  • 修復後有重新驗證
  • 回覆包含完整格式