前言

在前幾篇文章中，我們學會了建立專案、手動部署、以及設定網域與環境變數。本篇將帶你了解 Cloudflare Pages 最強大的功能之一：自動化部署。當你把程式碼推送到 GitHub，Cloudflare 會自動幫你建置並部署，不用再手動上傳檔案。

同時，我們也會學習如何使用特殊檔案來自訂網站行為，解決 React 單頁應用程式（SPA）常見的路由問題。

學習目標

讀完本篇後，你將能夠：

• 理解 Cloudflare Pages 的自動部署機制
• 設定 Preview Deployments 用於 PR 預覽
• 使用 redirects 與 headers 檔案自訂行為
• 解決 SPA 路由問題（React Router）

Git 整合與自動部署

連接 GitHub 儲存庫

當你在 Cloudflare Pages 建立專案時，可以選擇連接 GitHub 或 GitLab 儲存庫。連接後，每次推送程式碼都會自動觸發部署。

在 Dashboard 的 Workers & Pages 頁面中，你會看到專案設定：

Production branch: main

這表示當你推送到 main 分支時，會自動更新正式網站。

自動部署觸發條件

Cloudflare Pages 會在以下情況自動部署：

查看部署記錄

在專案頁面的「Deployments」分頁，你可以看到所有部署記錄：

Status    Branch    Commit           Time
-------------------------------------------
Success   main      abc1234          2 minutes ago
Success   feature   def5678          1 hour ago
Failed    develop   ghi9012          3 hours ago

點擊任一部署可以查看建置日誌，這對除錯非常有用。

Preview Deployments：PR 預覽功能

什麼是 Preview Deployment

Preview Deployment 是 Cloudflare Pages 的一個實用功能。每當你建立 Pull Request 或推送到非 main 分支，Cloudflare 會自動建置並部署到一個臨時網址。

這讓團隊成員可以在合併程式碼前，先預覽變更效果。

預覽網址格式

預覽網址的格式如下：

https://<commit-hash>.<project-name>.pages.dev

# 例如：
https://abc123def.my-react-app.pages.dev
Code language: PHP (php)

如果是 Pull Request，GitHub 會自動顯示預覽連結在 PR 頁面的檢查區塊。

在 PR 中查看預覽

當你在 GitHub 建立 PR 後，會看到類似這樣的檢查訊息：

Cloudflare Pages - Deploy Preview succeeded
View deployment: https://feature-branch.my-app.pages.dev
Code language: JavaScript (javascript)

點擊連結就能直接看到這個 PR 的變更效果，不需要在本地執行程式。

_redirects 檔案：解決 SPA 路由問題

SPA 路由問題是什麼

當你的 React 專案使用 React Router 時，網址會像這樣：

https://my-app.pages.dev/about
https://my-app.pages.dev/users/123
Code language: JavaScript (javascript)

問題來了：如果使用者直接在瀏覽器輸入 /about，或是重新整理頁面，Cloudflare 會嘗試尋找 /about/index.html 這個檔案。但這個檔案不存在，因為 React Router 是在瀏覽器端處理路由的。

結果就是看到 404 錯誤頁面。

使用 _redirects 解決

在你的專案 public 資料夾中建立 _redirects 檔案：

# public/_redirects

/*    /index.html   200
Code language: PHP (php)

這行設定的意思是：

狀態碼 200 很重要，它表示「直接回傳這個檔案的內容」，而不是告訴瀏覽器去轉址。這樣 React Router 就能正確接手處理路由。

更複雜的重定向規則

你也可以設定多條規則，規則會從上到下依序比對：

# public/_redirects

# API 請求轉發到後端
/api/*    https://api.example.com/:splat    200

# 舊路徑轉址到新路徑
/old-page    /new-page    301

# SPA fallback 放最後
/*    /index.html    200
Code language: PHP (php)

:splat 是萬用字元，會保留 * 匹配到的部分。例如 /api/users 會轉發到 https://api.example.com/users。

_headers 檔案：自訂 HTTP 標頭

什麼時候需要自訂標頭

自訂 HTTP 標頭可以用來：

• 設定快取策略
• 增加安全性標頭
• 啟用 CORS

建立 _headers 檔案

在 public 資料夾中建立 _headers 檔案：

# public/_headers

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

/assets/*
  Cache-Control: public, max-age=31536000, immutable
Code language: PHP (php)

常用標頭設定範例

安全性標頭：

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

快取設定：

/assets/*
  Cache-Control: public, max-age=31536000, immutable

這會讓 /assets/ 下的靜態檔案快取一年。因為 React 打包後的檔案名稱包含 hash，所以可以放心使用長時間快取。

Build 設定進階選項

在 Dashboard 中設定

在專案的「Settings」>「Build & Deploy」頁面，你可以調整建置設定：

Build command: npm run build
Build output directory: dist
Root directory: /
Node.js version: 18

常見框架的建置設定

環境變數在建置時使用

在建置過程中，你設定的環境變數會自動可用。例如設定了 VITE_API_URL，在程式碼中可以這樣使用：

// React 程式碼中
const apiUrl = import.meta.env.VITE_API_URL;
Code language: JavaScript (javascript)

注意：Vite 專案的環境變數需要以 VITE_ 開頭才會暴露給前端程式碼。

部署失敗排查技巧

查看建置日誌

當部署失敗時，第一步是查看建置日誌。在專案的「Deployments」頁面，點擊失敗的部署，展開「Build logs」：

[build]   Executing build command...
[build]   > npm run build
[build]
[build]   Error: Cannot find module 'react'
[build]
[build]   Build failed with exit code 1
Code language: JavaScript (javascript)

常見問題與解決方案

問題 1：找不到模組

Error: Cannot find module 'xxx'
Code language: JavaScript (javascript)

原因：package.json 中沒有列出相依套件，或是 node_modules 被加入 .gitignore（正常情況）但套件沒有正確安裝。

解決：確認 package.json 中有列出所有需要的套件。

問題 2：Node.js 版本不符

error: The engine "node" is incompatible with this module
Code language: JavaScript (javascript)

解決：在 Dashboard 的 Build 設定中調整 Node.js 版本。

問題 3：建置輸出目錄錯誤

部署成功但網站空白或顯示 404。

解決：確認「Build output directory」設定正確。Vite 是 dist，CRA 是 build。

本地測試建置

在推送前，先在本地執行建置確認沒問題：

npm run build

然後可以用簡單的 HTTP 伺服器預覽：

npx serve dist

檔案位置整理

最後整理一下特殊檔案應該放在哪裡：

my-react-app/
├── public/
│   ├── _redirects     <-- 重定向規則
│   ├── _headers       <-- HTTP 標頭設定
│   └── index.html
├── src/
│   └── ...
└── package.json
Code language: PHP (php)

這些檔案會在建置時被複製到輸出目錄，Cloudflare Pages 會自動讀取並套用。

系列總結

恭喜你完成了【Cloudflare Pages 部署 React】系列！讓我們回顧一下學到的內容：

• 第 1 篇：認識 Cloudflare Pages 與建立第一個專案
• 第 2 篇：本地準備 React 專案並手動部署
• 第 3 篇：設定自訂網域與環境變數
• 第 4 篇：自動化部署與進階設定

現在你已經具備完整的知識，能夠將 React 專案部署到 Cloudflare Pages，並利用自動部署功能加速開發流程。

重點回顧

• Git 整合後，推送程式碼會自動觸發部署
• Preview Deployments 讓每個 PR 都有預覽網址
• _redirects 檔案解決 SPA 路由的 404 問題
• _headers 檔案可設定快取與安全標頭
• 部署失敗時，查看建置日誌是第一步