Cloudflare Pages 除錯：從 build artifact 到 custom domain cache

Cloudflare Pages 的「部署成功」只代表 build/deploy pipeline 接受一個 artifact，不代表 custom domain 正在回傳同一內容。故障可能發生在 dependency install、build command、output directory、Functions、Pages deployment、DNS/TLS、zone rules 或 cache。有效除錯要逐層縮小，不把所有問題都歸因於 CDN。 截至 2026-07-29，Cloudflare 官方除錯文件仍建議先看 deployment build log，並指出 pages.dev 與 proxied custom domain 會受到不同 zone settings 影響。官方 Redirects 文件也說 _redirects 不會套用到由 Pages Functions 處理的 request，因此 SPA fallback 與 Functions route 可能互相覆蓋。 實作步驟 第一步固定 incident input：期望 commit SHA、Pages project、branch、build ID、build command、output directory、Node/package manager 版本、受影響 URL、首次發生時間。不要先重新 deploy；原始 log 與 artifact 是定位差異的證據。 第二步本地重建。使用 lockfile clean install 與完全相同 command/environment mode，檢查輸出根目錄真的有 index.html 、hashed assets、 _redirects 、 _headers 、robots/sitemap。Vite 常見 output 是 dist ，但以實際 config 為準。 npm ci npm run build find dist -maxdepth 2 -type f | sort | sed -n '1,120p' test -f dist/index.html 第三步查看 Cloudflare build log，分辨 initializing、building、deploying 哪段失敗。若 install fail，比對 runtime、lockfile、private registry；build fail 檢查 env name/secret 是否只在 preview 或 production；deploy fail 查 Functions/config。不要把 secret value貼進 issue。 第四步以 deployment-specific *.pages.dev URL 驗證 artifact。檢查首頁、hashed JS/CSS、深層 route、API/Function、404、robots/sitemap 與 version marker。如果 pages.dev 已錯，問題在 artifact/project，而非 custom domain。 第五步只在 pages.dev 正確時查 custom domain。用 dig / curl -I 比對 DNS、status、Location、ETag、Age、CF-Cache-Status、Content-Type 與 body hash。Cloudflare 官方指出 proxied custom domain 的 zone cache/rules 會加入行為；暫時 DNS-only 是診斷手段，不是無條件永久解法。 第六步檢查 routing precedence。 _redirects 每行順序有意義；static rule 與 wildcard 先後要測試。如果 Functions 捕捉該 route，需在 function code 實作 redirect/fallback 或排除 route，不能期待 _redirects 生效。SPA fallback 不應把不存在的 asset、API 與 SEO 404 全改成 200 index。 第七步才處理 cache。先用 query/cache-busting、deployment domain 與 custom domain 比較，確認 origin artifact 新、custom response 舊。優先 purge 單一 URL/資產；若 zone rule Cache Everything 干擾 Pages，移除或縮小。purge 後重新抓 response/body hash，不以 dashboard 顯示成功作結。 失敗與復原 build 失敗時回到最後成功 deployment 繼續服務，保存新 build log。修 lockfile/runtime/env 後以新 commit 觸發，避免在 dashboard 中反覆改 command 而 repository 無法重現。 pages.dev 404 root 常代表 output directory 錯或缺 index.html 。修 project build config/ artifact；不要用 custom redirect 隱藏根因。若只有深層 SPA route 404，設計精確 fallback 並另測真 404。 custom domain stuck verifying 時檢查 DNS、Access/redirect/Worker 是否擋 HTTP validation、CAA 與 zone hold，依官方 steps 處理。不要刪 production DNS 再盲目重加；先保存 records。 若錯誤 cache rule 造成舊 HTML 參考已移除 hashed asset，先回滾到相容 artifact或 purge HTML，確認所有 asset 200，再修 rule。rollback 後仍需 custom domain cache-busted live verification。 驗證指令 curl -sSI https://DEPLOYMENT.pages.dev/ curl -sSI 'https://example.com/?verify=COMMIT_SHA' curl -sS https://DEPLOYMENT.pages.dev/robots.txt | shasum -a 256 curl -sS 'https://example.com/robots.txt?verify=COMMIT_SHA' | shasum -a 256 dig +short example.com 對 root、深層 route、缺頁、hashed asset、redirect、Function 與 SEO 檔建立表格，比較 pages.dev/custom domain 的 status、content type、location、hash 與 cache header。以 domcontentloaded 加關鍵元素做 browser smoke；含長連線網站不要只依 networkidle 。 官方來源 Cloudflare Debugging Pages Cloudflare Pages Redirects Cloudflare Serving Pages 延伸閱讀 在 技術文章 查看 React prerender 與 production stack。 從 課程總覽 練習 Pages deploy verification。 可由 聯絡頁 提供 deployment URL 與 redacted headers。