GitHub PR 與 Cloudflare Pages 免費部署流程教學

annie · September 10, 2026, 3:16am

用 GitHub Pull Request 搭配 Cloudflare Pages 建立免費部署流程：分支開發、PR 審查、自動預覽、合併後自動上線，並提供建置設定、環境變數與上線檢查清單。

GitHub Pull Request 搭配 Cloudflare Pages，可以組成一套免費且適合團隊協作的網站部署流程。開發者在自己的分支修改程式碼，透過 PR 進行審查與預覽，確認後合併至 main，Cloudflare Pages 便會自動建置並部署正式網站。這種做法能降低直接修改正式環境的風險，也讓團隊成員不需要各自擁有付費部署平台帳號。

架構概念

建議的流程如下：

開發者在自己的分支修改
        ↓
建立 Pull Request
        ↓
自動執行程式碼檢查
        ↓
產生預覽網站
        ↓
審查並確認內容
        ↓
Merge 至 main
        ↓
Cloudflare Pages 自動部署正式網站

實際分工：

開發者：在個人分支進行修改並提交 PR。
審查者：查看程式碼差異、預覽網站與檢查結果。
GitHub：管理原始碼、分支與 PR 流程。
Cloudflare Pages：在程式碼合併後自動建置並部署網站。

為什麼採用這種方式

保留 GitHub 作為程式碼中心

GitHub repository 可以繼續作為唯一的原始碼來源，不需要因為更換部署平台而搬遷專案。

透過 Pull Request 管理變更

所有正式版本的修改都先經過 PR 審查，避免開發者直接修改 main，並保留完整的變更紀錄。

自動產生預覽環境

Cloudflare Pages 可以針對分支或 PR 建立預覽部署，讓團隊在合併前直接查看網站實際呈現效果。

合併後自動部署

當 PR 合併到指定的 production branch，Cloudflare Pages 會自動執行建置與部署，不需要人工重新上傳檔案或按下發布按鈕。

開始前的準備

開始設定前，請確認：

已有 GitHub repository。
專案可以在本機正常建置。
已確認網站使用的 framework 與建置指令。
已確認輸出目錄，例如 dist、build 或其他 framework 預設目錄。
已確認環境變數與敏感資訊的管理方式。
已確認是否使用後端 API、Serverless Functions 或外部資料庫。
已確認網域 DNS 可以由 Cloudflare 管理，或準備依照平台指示完成 DNS 設定。

Git 分支策略

建議不要直接在 main 分支開發，而是為每一項工作建立獨立分支。

例如：

main
├── feature/new-page
├── fix/mobile-layout
└── content/update-copy

基本流程：

git checkout main
git pull origin main

git checkout -b feature/your-change

完成修改後：

git add .
git commit -m "Add requested changes"
git push -u origin feature/your-change

接著在 GitHub 建立 Pull Request，將該分支合併至 main。

設定 GitHub Pull Request

建議的 PR 流程

每個 PR 通常應包含：

變更目的。
修改內容摘要。
受影響的頁面或功能。
測試方式。
預覽網址。
已知限制或待處理事項。

PR 說明可以使用以下格式：

## 變更目的

說明這次修改要解決的問題或達成的目標。

## 修改內容

- 修改項目一
- 修改項目二
- 修改項目三

## 測試方式

- [ ] 本機建置成功
- [ ] 已檢查主要頁面
- [ ] 已確認手機版顯示
- [ ] 已確認相關表單或 API 功能

## 預覽

提供預覽部署網址。

## 備註

列出已知限制、需要審查的部分或後續工作。

建議保護 `main` 分支

可以在 GitHub 設定 branch protection rules，要求：

必須透過 Pull Request 合併。
必須通過自動化檢查。
至少一位成員審查後才能合併。
禁止強制推送至 main。
必要時啟用分支必須更新至最新版本的規則。

這些設定能將程式碼審查流程制度化，降低誤部署與未經審查變更的風險。

設定 Cloudflare Pages

連結 GitHub repository

在 Cloudflare Pages 建立新專案時，選擇從 Git repository 部署，接著：

連結 GitHub 帳號。
選擇要部署的 repository。
選擇 production branch，通常是 main。
設定 framework preset。
設定建置指令。
設定輸出目錄。
設定必要的環境變數。
建立專案並執行第一次部署。

常見建置設定

不同 framework 的設定會有所不同。以下是常見範例：

專案類型	建置指令	輸出目錄
Vite	`npm run build`	`dist`
React	`npm run build`	依專案設定
Next.js	依 Cloudflare 支援方式設定	依 adapter 或 framework 設定
Astro	`npm run build`	`dist`
Hugo	`hugo`	`public`
純靜態網站	不需要	專案根目錄或指定目錄

實際設定應以專案的 framework 文件與 Cloudflare Pages 支援狀況為準。

預覽部署與正式部署

Cloudflare Pages 通常可以將不同 Git 分支對應至不同部署環境：

main：正式環境。
功能分支：預覽環境。
Pull Request：提供審查用的預覽網址。

推薦的工作方式：

開發者提交分支。
GitHub 建立 PR。
Cloudflare Pages 自動產生預覽部署。
團隊查看預覽網址。
確認自動化檢查結果。
審查者確認 PR。
合併至 main。
Cloudflare Pages 自動部署正式網站。

預覽環境應盡量接近正式環境，但要避免使用正式資料庫進行具破壞性的測試。若網站包含表單、會員、付款或資料寫入功能，建議為預覽環境配置獨立的測試服務。

環境變數管理

不要將 API key、資料庫密碼、OAuth secret 或其他敏感資訊直接提交至 GitHub。

建議將環境區分為：

Development
Preview
Production

不同環境使用不同的設定，例如：

API endpoint。
資料庫連線。
第三方服務金鑰。
OAuth callback URL。
分析工具設定。
Feature flag。

本機可以使用 .env.local，並將相關檔案加入 .gitignore：

.env
.env.local
.env.*.local

Cloudflare Pages 則應在專案設定中加入環境變數，並分別設定 Preview 與 Production 的值。

API 與 Serverless Functions

如果網站只是靜態前端，可以直接部署編譯後的檔案。

如果專案包含 API，則需要確認 API 的執行方式，例如：

Cloudflare Pages Functions。
Cloudflare Workers。
外部 API 服務。
Supabase、Neon 或其他雲端資料庫。
既有的獨立後端伺服器。

在搬遷或重新設定部署平台時，應特別檢查：

API route 是否相容。
Runtime 是否支援 Node.js、Deno 或其他執行環境。
環境變數名稱是否一致。
CORS 設定是否正確。
Authentication callback 是否需要更新。
預覽環境是否使用正確的 API endpoint。
Functions 是否需要額外的部署設定。

如果前端原本依賴特定平台提供的 serverless API，不能只搬移前端檔案，還需要重新評估 API 與 runtime 的相容性。

網域與 DNS 切換

正式切換前，建議先完成以下事項：

確認 Cloudflare Pages 部署成功。
透過預覽網址檢查主要頁面。
確認 HTTPS 憑證正常。
確認 API、表單與登入功能。
確認 robots.txt、sitemap 與 canonical URL。
確認 DNS 設定與現有電子郵件服務不受影響。
確認舊平台仍可在切換期間回復使用。

切換網域時，建議保留原始部署一段時間。完成 DNS 切換後，應從不同網路與裝置檢查：

根網域。
www 子網域。
主要頁面。
圖片與靜態資源。
表單與 API。
第三方登入。
網站分析與追蹤工具。

檔案大小與建置限制

部署前應檢查專案是否包含大型檔案。影片、原始影像、模型檔案與備份檔案通常不適合直接放在 Git repository 或網站部署輸出目錄中。

建議：

大型影片使用影片託管或物件儲存服務。
圖片使用 CDN 或影像處理服務。
模型檔案使用專用模型儲存空間。
備份檔案不要放入正式網站的 build output。
使用 Git LFS 或其他適合的檔案儲存方案管理大型版本檔案。
在 CI 中檢查單檔大小與整體輸出大小。

部署前可以執行：

npm run build
du -sh dist
find dist -type f -size +25M

實際限制會依方案、功能與平台政策而變動，正式上線前應確認 Cloudflare Pages 最新的平台限制文件。

自動化檢查

建議在 Pull Request 中加入自動化檢查，例如：

name: Validate

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - run: npm run build

實際步驟應依專案的 package manager 與 framework 調整，例如使用 pnpm、yarn 或其他工具時，應改用對應的安裝與快取設定。

上線前檢查清單

GitHub 與程式碼

main 分支受到保護。
所有變更透過 Pull Request 合併。
PR 已完成程式碼審查。
自動化檢查全部通過。
沒有提交敏感資訊。
已確認 dependency lockfile 正確。

Cloudflare Pages

Repository 已正確連結。
Production branch 設定正確。
建置指令正確。
輸出目錄正確。
Preview 與 Production 環境變數已分開。
預覽部署可以正常開啟。
正式部署成功。

網站功能

首頁與主要頁面正常。
手機版與桌面版顯示正常。
圖片、字型與靜態資源正常載入。
表單可以正常提交。
API 回應正常。
登入與權限功能正常。
404 頁面設定正確。
SEO metadata、robots.txt 與 sitemap 正常。
Analytics 與必要的第三方服務正常。

網域與營運

DNS 設定完成。
HTTPS 正常。
根網域與 www 設定正確。
電子郵件相關 DNS 紀錄未被破壞。
已建立回復方案。
已確認錯誤監控與通知方式。

常見問題

PR 預覽成功，但正式部署失敗

常見原因包括：

Production 使用了不同的環境變數。
main 分支的程式碼與 PR 分支不同。
正式環境缺少必要的 secret。
建置指令或輸出目錄設定錯誤。
正式環境使用了不同的 runtime 設定。

可以先比較 Preview 與 Production 的部署紀錄、環境變數名稱與建置輸出。

網站顯示空白頁面