跳轉到

3.3 部署 Pages：Git 整合、自動 CI 與自訂網域上線#

本節目標#

把 3.2 節建好的專案真正推上全球邊緣節點。本節提供兩條部署路徑——Dashboard 的 Git 整合（適合常態開發，自動 CI）、wrangler CLI（適合快速上線與自動化腳本），完整走一遍 Pages 的建置設定（build command 與 output 目錄）、CI 觸發過程與 build log 的閱讀，最後把預設的 *.pages.dev 換成自己的網域。

路徑一：Dashboard + Git 整合（推薦）#

Git 整合的核心思想：Git 儲存庫是單一真相來源，Pages 是它的自動化快取鏡。

git push → GitHub → Webhook → Cloudflare Pages CI
         → git clone → npm run build → 上傳靜態產物 → 全球上線

操作步驟#

  1. 先把 3.2 節的專案推上 GitHub（或 GitLab）： 
    git remote add origin git@github.com:你的帳號/demo-pages.git
git push -u origin main
  2. Dashboard → Workers & Pages → Create application → Pages → Connect to Git，授權並選擇 demo-pages 儲存庫。
  3. 填寫建置設定（這是本步驟唯一的思考點）：
設定 Astro 值 React+Vite 值
Framework preset Astro Vite / React
Build command npm run build npm run build
Build output directory dist dist
Root directory /（monorepo 才改） /
  1. 按 Save and Deploy，一分多鐘後拿到 https://demo-pages.pages.dev —— 你的網站已經在全球數百個邊緣節點。

CI 的觸發過程與 build log#

之後每一次 git push 都會觸發一次建置。到 專案 → Deployments 可以看到歷次部署，點進去展開 build log：

Cloning repository from github.com/.....
Cloned in 3.2s
Found commit 1a2b3c4 "feat: 新增 about 頁"
Installing dependencies with npm...         ← npm ci
npm install completed in 28s
Running "npm run build"
  ▶ astro build
  ▷ Building pages... done in 6s
Found 12 static routes
✓ Build complete. Uploading dist/ (34 files)
Deploying to https://demo-pages.pages.dev ... ✓ Deployment complete

讀 log 的兩個關鍵：Composer/commit SHA（每個部署都釘住一個確切的 commit，審計時「哪一次推上去的」無可抵賴），以及輸出目錄是否被正確偵測——這裡若打錯（例如把 output 寫成 build），日誌會立刻出現找不到 dist 的錯誤，這是最常見的第一個坑。

Pull Request 也會自動建置成 Preview 部署（URL 如 https://abc123.demo-pages.pages.dev）——CI 的力量在於它是免維護的：不需要自己養一台 CI 機器。

路徑二：wrangler CLI#

wrangler 是 Cloudflare 的官方 CLI（第 4 章會大量使用）。Git 整合之外，可以直接從本機推部署：

npm install -g wrangler
wrangler login          # 瀏覽器 OAuth 授權
wrangler pages init demo-pages
wrangler pages deploy dist --project-name=demo-pages

流程對比：

Git 整合 wrangler deploy
觸發 git push 自動 手動命令（可寫進任何腳本）
CI Cloudflare 雲端建置 本機或你自己的 CI 建置
產物偵測 dashboard 設定 + Wrangler 內建框架偵測 你 deploy 的那個目錄就是產物
適合 常態開發、團隊 腳本化、單檔快速上線、離線 CI

差別的本質是CI 要把拉力放哪一邊：Git 整合是 Cloudflare「拉」你的儲存庫；wrangler 是你「推」建置完成的產物。本書第 5、6 章的全棧專案會兩者並用——前端走 Git 整合，後端 Workers 走 wrangler。

自訂網域上線：從 *.pages.dev 到 example.com#

*.pages.dev 只是臨時門牌。正式上線要綁定自己的網域——前提是網域的 DNS 已託管在 Cloudflare（若還沒，見 2.2 節）：

  1. 專案 → Custom domains → Set up a custom domain → 輸入 example.com（或 www.example.com）。
  2. 選建立 CNAME 記錄：Pages 會自動寫入 name: example.com / CNAME: demo-pages.pages.dev（根網域用 CNAME 展平技術處理）。
  3. 一鍵完成 HTTPS：2.4 節的邊緣憑證機制自動簽發並掛上。
DNS 解析結果：
example.com.   →  CNAME  demo-pages.pages.dev.  →  Pages 邊緣叢集
                        + 全球任一節點自動對應**該節點**的 TLS 憑證

原理值得停留在兩行：Pages 不是把你的域名轉發到某台伺服器，而是讓你的域名成為全球任一邊緣節點上這個專案的名字——CNAME 只是把 DNS 指向邊緣叢集，同一叢集後面服務所有客戶的域名。

驗收清單#

  • https://example.com 開頭是 200，且出現你的首頁
  • curl -I https://example.com 中 server: 帶有 Cloudflare 抬頭
  • HTTPS 盒子已生效（2.4 節憑證）；若有舊 HTTP 連結，Pages 預設已 301 重定向到 HTTPS
  • 推了一個改動，觀察 git push 到 Pages 上的自動部署流程完整跑一輪

小結與練習#

本節把專案推上雲端：兩條路徑（Git 整合 = Cloudflare 拉、wrangler = 你推）、三個名詞（build command、output 目錄、build log）、把 *.pages.dev 換成 example.com，並用 CNAME + 邊緣憑證完成 HTTPS。

練習

  1. 刻意把 Build output directory 設成錯誤路徑（例如 builds），觀察 build log 的失敗訊息，體驗 CI 的排錯流程後改回並重新部署。
  2. 開一個分支推上 GitHub，觀察 Pages 如何自動產生 Preview 部署並回寫到 PR。
  3. 用 wrangler 把本機一個純 HTML 資料夾 wrangler pages deploy 上去，與 Git 整合專案在同一個 Dashboard 中對比兩種部署在 Deployments 列表的差異（來源標示 Git vs Direct Upload）。

下一節深入快取與版本管理：immutable 部署、_headers、Preview 環境與 Rollback。