Cloudflare Pages 預覽環境設定教學 — 編譯摘要

濃縮

核心結論

1. Cloudflare Pages 的預覽部署需要明確的分支設定（dev → 預覽、main → 正式），且 Node.js 版本需透過 .node-version 檔案指定，否則預設 Node 18 會導致 Astro 5 建置失敗。
2. 預覽網址預設公開，需透過 [[Zero Trust Access]] 的 Email OTP 驗證來保護未上線內容。
3. Cloudflare 萬用字元 * 不包含根網域本身，需要額外設定一筆無子網域的規則。

關鍵證據

• 部署失敗時錯誤訊息僅顯示「an internal error occurred」，沒有有用的 log，根因是 Node.js 版本不符。
• Wrangler CLI 可在終端機直接查看部署狀態，避免頻繁切換到 Dashboard。

質疑

依賴哪些前提假設？

• 假設使用 Git 分支策略（dev/main）來區分環境，不適用於 trunk-based development。
• 假設團隊規模小，Email OTP 驗證的管理成本可接受。
• 假設 Cloudflare 作為唯一的部署與存取控制平台。

換產業/規模/技術棧還成立嗎？

• 分支預覽的概念在 [[Vercel]]、Netlify 等平台同樣存在，但各平台的設定細節不同。
• 大型團隊可能需要更細粒度的存取控制（如 RBAC），Email OTP 在人數多時管理困難。
• 非 Astro 框架同樣會遇到 Node.js 版本問題，.node-version 是跨平台的解法。

反例或邊界條件

• 若團隊成員頻繁變動，每次都要到 Dashboard 加 Email 會成為瓶頸。
• Zero Trust Access 的免費方案有 50 位使用者上限。

對標

其他領域的類似現象

• 建築業的工地預覽：模型或 3D 渲染供客戶確認，但不對外公開，類似預覽環境的存取控制。
• 出版業的校稿流程：內部預覽版本只有編輯團隊可看。

知識可遷移到哪些場景

• 任何需要「預覽→確認→上線」流程的部署平台。
• [[預覽環境存取控制]]的設計模式適用於 API 文件預覽、設計稿預覽等場景。

關聯概念

• [[預覽環境存取控制]]
• [[Zero Trust Access]]
• [[分支部署策略]]
• [[Cloudflare Pages]]
• [[Node.js 版本管理]]