Cloudflare Pages 預覽環境設定教學：分支部署 + Zero Trust 存取控制

最近我們團隊在幫公司官網從 Vercel 搬到 Cloudflare Pages，過程中遇到一個需求：我們希望每次推程式碼到 dev 分支時，Cloudflare 能自動部署一份預覽版本讓團隊成員確認，確認沒問題後再合併到 main 正式上線。同時，預覽網址不能讓外部人員隨意存取。

這篇文章記錄我們實際操作的過程，以及中間踩到的坑。

我們想要的架構

• dev 分支 → 自動部署到 dev.codotx.pages.dev（預覽）
• main 分支 → 自動部署到 codotx.com（正式環境）
• *.codotx.pages.dev 要加上存取控制，只有團隊成員能看到

建立 dev 分支

第一步很簡單，在本機建立 dev 分支並推到 GitHub：

git checkout -b dev
git push -u origin dev

推完之後 Cloudflare Pages 會自動偵測到新分支，並觸發一次 Preview 部署。我們到 Cloudflare Dashboard 的「部署」頁籤確認，確實看到了一筆 dev 分支的部署紀錄。

第一個坑：部署失敗

結果部署失敗了。我們在 Dashboard 上只看到狀態顯示「Failure」，錯誤訊息是「an internal error occurred」，完全沒有有用的 log。

後來想到問題可能出在 Node.js 版本。我們的專案用的是 Astro 5，需要 Node.js 22 以上，但 Cloudflare Pages 預設用的是 Node 18。奇怪的是 main 分支之前部署都成功，所以我們沒有第一時間想到這個問題。

解法是在專案根目錄建立一個 .node-version 檔案：

22

推送之後，dev 分支就成功部署了。我們也把這個檔案合併回 main，避免未來出問題。

確認分支控制設定

為了確保 Cloudflare Pages 會正確處理不同分支的部署，我們到設定頁面確認了以下項目：

• Production 分支：main
• 預覽分支：設為「自訂」，確保 dev 有被包含
• 組建命令：npm run build
• 組建輸出：dist

安裝 Wrangler CLI

每次都要開 Dashboard 看部署狀態太麻煩了，所以我們裝了 Cloudflare 的 CLI 工具 Wrangler：

npm install -g wrangler
wrangler login

登入後就能在終端機直接查看部署列表：

wrangler pages deployment list --project-name=codotx

我們的 Cloudflare 帳號綁了多個 Account，所以還需要額外指定 Account ID，不然會報錯：

CLOUDFLARE_ACCOUNT_ID=你的帳號ID wrangler pages deployment list --project-name=codotx

這樣就能快速確認每次推送後的部署狀態是成功還是失敗，不用再切到瀏覽器了。

日常部署流程

設定完成後，日常開發的流程變成：

1. 在 dev 分支開發並提交
2. git push origin dev → 自動部署到 dev.codotx.pages.dev
3. 到預覽網址確認沒問題後，合併到 main：

git checkout main
git merge dev
git push origin main

4. Cloudflare 自動部署到 codotx.com

第二個坑：預覽網址任何人都能看到

部署流程搞定之後，我們發現了另一個問題：codotx.pages.dev 和 dev.codotx.pages.dev 是完全公開的，任何人只要知道網址就能看到還沒上線的內容。

我們需要對這些預覽網址加上存取控制，但 codotx.com 正式站不能受影響。

方案選擇

一開始我們考慮用 Cloudflare Pages Function 寫 HTTP Basic Auth middleware，但後來決定用 Cloudflare 原生的 Zero Trust Access，因為：

• 不需要管理密碼
• 用 Email OTP（一次性驗證碼）驗證，比傳統帳密安全
• 設定完全在 Dashboard 操作，不需要改程式碼

建立 Access 應用程式

進入 Zero Trust → Access 控制 → 應用程式 → 新增應用程式 → 選擇 Self-hosted。

在「基本資訊」頁籤設定：

• 應用程式名稱：codotx - Cloudflare Pages
• 工作階段持續時間：24 hours

第三個坑：萬用字元不包含根網域

公用主機名稱我們一開始只設了子網域 * + 網域 codotx.pages.dev，以為這樣就能保護所有 *.codotx.pages.dev 的網址。結果 dev.codotx.pages.dev 確實被擋住了，但 codotx.pages.dev 本身還是公開的。

原來 Cloudflare 的萬用字元 * 只匹配有子網域的情況（如 dev.codotx.pages.dev），不包含根網域本身。所以我們需要加入兩筆規則：

• 子網域 * + 網域 codotx.pages.dev（保護 dev.codotx.pages.dev 等子網域）
• 子網域留空 + 網域 codotx.pages.dev（保護 codotx.pages.dev 本身）

設定存取原則

切換到「原則」頁籤，建立允許存取的規則：

• 原則名稱：Allow Members - Cloudflare Pages
• 動作：Allow
• 選取器：Emails
• 值：加入團隊成員的 Email 地址

設定完成後，訪問任何 *.codotx.pages.dev 的網址都會跳出 Cloudflare 的驗證頁面。輸入已授權的 Email 後，信箱會收到一封含有驗證碼的信，輸入後就能存取，24 小時內不用再重新驗證。

而 codotx.com 完全不受影響，外部訪客可以正常瀏覽。

總結

整個設定過程中踩了三個坑：

1. Node.js 版本不對 — Cloudflare Pages 預設用 Node 18，Astro 5 需要 Node 22，用 .node-version 解決
2. 預覽網址公開 — 用 Zero Trust Access 的 Email OTP 驗證來保護
3. 萬用字元不含根網域 — 需要分開設定 * 和根網域兩筆規則

最終達成的效果：

• 推到 dev 自動產生預覽，只有團隊看得到
• 合併到 main 自動上線到正式站
• 不需要管理任何密碼，用 Email 驗證碼搞定