本站及遊戲大廳一年來累積 100+ 次部署，踩過幾個 Cloudflare Pages 文件沒寫清楚的坑。這篇給後來的人省時間。
陷阱 1：Universal SSL 只覆蓋兩層子網域
免費版 Cloudflare 的 Universal SSL 只簽 example.com + *.example.com。如果你用三層子網域（如 api.game.example.com），瀏覽器會回 ERR_SSL_VERSION_OR_CIPHER_MISMATCH。
修法：把子網域留在兩層內。本站把 api.game.hao0321.com 改成 api.hao0321.com 才解決。
陷阱 2：_headers 必須在輸出根目錄
很多人把 _headers 放在 src/ 或 public/，部署後發現 header 沒生效。
修法：_headers 要在 wrangler pages deploy <dir> 那個 <dir> 的根。對 zero-build 專案是專案根、對 Vite 專案是 dist/。建構流程要把 _headers 也複製過去。
陷阱 3：Direct Upload Mode 跟 Git 不會自動同步
Pages 有兩種模式：
- Git Integration：push 自動部署
- Direct Upload：用
wrangler pages deploy手動部署
選 Direct Upload 後，git push 不會觸發任何 deploy。我曾經以為 push 完就上線，結果發現 production 還是舊版。
修法：寫一條 alias：
alias deploy='git push origin main && \ wrangler pages deploy . --project-name=YOUR_PROJECT \ --branch=main --commit-dirty=true'
陷阱 4：Preview Deployment 不會自動清除
每次 wrangler pages deploy 都產生一個 preview URL（如 https://abc123.your-project.pages.dev）。免費版這些 preview 永久保留，累積上百個之後 dashboard 載入超慢。
修法：
npx wrangler pages deployment list --project-name=YOUR_PROJECT # 找到舊的 deployment ID npx wrangler pages deployment delete <id> --project-name=YOUR_PROJECT
或寫個 script 批次刪除超過 30 天的 preview。
陷阱 5：wrangler.toml 在子目錄會被誤抓
本站結構：
/ ← 主站 (Pages) /game/ ← 遊戲大廳 (另一個 Pages 專案) /game-api/ wrangler.toml ← Worker 設定
當 wrangler pages deploy 在主站根目錄執行時，wrangler 會「向下找」找到 game-api/wrangler.toml，把它的設定當成 Pages 設定，跳出警告：
WARNING: We detected a configuration file at game-api/wrangler.toml but it is missing the "pages_build_output_dir" field
實際上沒影響，但每次部署都看到這個警告很煩。
修法：在 Pages 部署目錄根放一個空 wrangler.toml，明確指定 pages_build_output_dir = "."。
額外：CWD 陷阱（自己踩的）
用腳本自動部署時，最常見的錯誤是「CWD 不在預期位置」。例如：
# 危險寫法 cd game-api && wrangler deploy # 然後接著 wrangler pages deploy . --project-name=hao0321-studio # 此時 CWD 是 game-api/，部署的是 game-api/ 而不是專案根！
修法：每次 deploy 都用絕對路徑：
wrangler pages deploy "/full/path/to/project" \ --project-name=hao0321-studio --branch=main
額外：commit message UTF-8 問題
如果 git 最近一次 commit message 是中文且編碼異常，wrangler pages deploy 會回：
Invalid commit message, it must be a valid UTF-8 string. [code: 8000111]
修法：手動指定 commit message：
wrangler pages deploy . --commit-message="Manual deploy"
結語
Cloudflare Pages 90% 體驗很順，剩下 10% 是這些細節文件沒寫清楚。希望這份清單能幫到後來的人。
還有其他踩過的坑想分享，歡迎寄信 lo246179268@gmail.com。