Cloudflare Pages 架站完全指南

#建構部署 #Cloudflare #Pages #免費架站 #靜態網站

Cloudflare Pages 是以 Git 為核心的前端與全端架站平台，靜態請求與頻寬皆無上限，免費方案即可商用，並能透過 Pages Functions 擴充為全端應用。

💡 免費起步：Pages 免費方案頻寬與靜態請求無上限、免費也可商用，連 Git 推送即自動部署。實際操作見 快速開始。

目錄

• 什麼是 Cloudflare Pages？
• 核心特性
• 快速開始（免費）
• Pages 與 Workers 的關係
• Pages Functions（全端能力）
• 部署模型
• 免費方案額度與限制
• 什麼情境適合 Pages？
• Pages vs Vercel
• 實戰範例
• 最佳實踐
• 常見問題
• 總結

什麼是 Cloudflare Pages？

Cloudflare Pages 是一個以 Git 驅動的前端與全端架站平台。連接程式碼倉庫後，每次推送都會自動建置並部署到 Cloudflare 的全球邊緣網路。

一句話理解：把 Git 倉庫接上去，推送後就會自動建置成網站並佈到全球 CDN。

核心定位是靜態網站託管，再以可選的 Pages Functions 補上伺服器端邏輯，讓純前端站點也能擁有 API、表單處理等全端能力。

核心特性

快速開始（免費）

有兩條主要路徑。路徑 A 適合長期專案與團隊協作，路徑 B 適合快速上傳已建好的產物。

路徑 A：Dashboard 連 Git 倉庫

1. 連接倉庫：在 Cloudflare Dashboard 進入 Workers & Pages，選擇 Pages，授權並選取 GitHub / GitLab 倉庫。

2. 設定建置：填入 build command（如 npm run build）與 build output 目錄（如 dist），選擇對應的框架預設。

3. Deploy：按下部署，後續每次 push 到該分支就會自動觸發建置與部署。

路徑 B：用 wrangler 直接部署

1. 安裝 wrangler：

npm i -g wrangler

2. 建置產物：先在本機產生輸出目錄（例如 ./dist）。

3. 上傳部署：

wrangler pages deploy ./dist

此方式不需要連 Git，適合 CI 自訂流程或一次性上傳。

Pages 與 Workers 的關係

兩者常被混淆，定位其實不同：

• Pages 偏向「架站 / 前端 + 邊緣 CDN」，以託管靜態資產與整站部署為核心。
• Workers 偏向「邊緣運算」，以撰寫在邊緣執行的函式邏輯為核心。

關鍵澄清：Pages Functions 底層就是 Workers。在 Pages 專案 functions/ 目錄中的程式碼，執行時與 Workers 共用同一個執行環境，其請求也計入 Workers 的免費額度。

若需求是「先有一個網站、再順帶加上少量動態端點」，從 Pages 入手較直接；若需求是「以邊緣函式為主體、沒有整站前端」，則直接用 Workers。延伸閱讀：Cloudflare Workers。

Pages Functions（全端能力）

Pages Functions 讓靜態站點獲得伺服器端能力，無需另外架後端。

• 檔案路由：在專案根目錄建立 functions/ 目錄，檔案路徑即對應 URL 路徑。例如 functions/api/hello.ts 對應 /api/hello。
• bindings：可透過 bindings 連接 D1（SQL）、KV（鍵值）、R2（物件儲存）等資源，詳見 Cloudflare 儲存（D1/R2/KV）。
• 底層為 Workers：執行模型與 Workers 一致，請求計入 Workers 免費額度。

範例 functions/api/hello.ts：

export async function onRequest(context) {
  return new Response(
    JSON.stringify({ message: "hello from pages function" }),
    { headers: { "content-type": "application/json" } }
  );
}

部署後對 /api/hello 的請求即會由此函式處理。

部署模型

部署流程以 Git 為驅動：

git push → 觸發 build → 產出靜態資產 → 佈署到全球邊緣

• Production vs Preview：推送到 Production 分支會更新正式站點；其他分支與 PR 則產生獨立的 Preview 部署，URL 互不影響，便於審查。
• 不可變部署：每次部署都是一個不可變的快照，保留歷史紀錄，可隨時 rollback 到先前的部署。
• build 設定：build command 與 output 目錄在專案設定中指定，框架預設可自動填入常見組合。

免費方案額度與限制

下列數字以官方文件為準，實際配額請於 Dashboard 與官方說明確認。

需要注意：Functions 的請求量與 Workers 共用每日 100K 的免費額度，若同時使用 Workers，兩者會一起計算。

什麼情境適合 Pages？

純前端或前端為主、僅需少量 API 的專案最契合 Pages；若主體是長時間後端運算或完整伺服器框架，則應考慮其他平台或服務。

Pages vs Vercel

兩者都提供 Git 驅動的前端部署，差異主要在計費模式與框架整合。

取捨：若重視頻寬與商用彈性，Pages 在免費方案上限制較寬；若專案以 Next.js 為主、看重原生整合與 DX，Vercel 的體驗較完整。延伸閱讀：Vercel 指南。

實戰範例

範例 1：連 Git 部署 Vite / 靜態站

在 Dashboard 的建置設定中填入：

Build command:   npm run build
Build output:    dist

之後每次 push 即自動建置並部署該 output 目錄。

範例 2：wrangler 直接上傳

npm run build
wrangler pages deploy ./dist

不經 Git，直接把本機產物上傳成一次部署。

範例 3：一個 Pages Function

functions/api/hello.ts：

export async function onRequest() {
  return new Response("hello", {
    headers: { "content-type": "text/plain" },
  });
}

範例 4：綁定 D1 的簡單查詢示意

functions/api/users.ts（需先在專案設定中建立名為 DB 的 D1 binding）：

export async function onRequest(context) {
  const { results } = await context.env.DB
    .prepare("SELECT id, name FROM users LIMIT 10")
    .all();
  return new Response(JSON.stringify(results), {
    headers: { "content-type": "application/json" },
  });
}

D1 等資源的設定細節見 Cloudflare 儲存（D1/R2/KV）。

最佳實踐

• 善用 Preview 部署做 review：在分支或 PR 的 Preview URL 上驗證後再合併到 Production。
• 正確設定 build output 目錄：output 目錄填錯是部署後白頁或 404 的常見原因。
• 靜態優先：能以靜態方式產出的內容就走靜態，享受免計量的靜態請求與無上限頻寬。
• 需要動態才用 Functions：僅在表單、API 等動態需求時加入 Pages Functions，避免不必要地消耗 Workers 額度。
• 自訂網域與 HTTPS：綁定自有網域並確認 HTTPS 已自動套用。
• 注意 Functions 計入 Workers 額度：規劃流量時，將 Functions 請求與 Workers 的每日 100K 共用額度一併估算。

常見問題

Q：Pages 和 Workers 差在哪、該用哪個？ A：Pages 以架站 / 前端託管為核心，Workers 以邊緣運算為核心。若要「先有網站、再加少量動態端點」用 Pages；若主體是邊緣函式、沒有整站前端則用 Workers。

Q：Pages 真的頻寬無限嗎？ A：所有方案皆無頻寬上限，靜態資產請求也免費不計量。實際條款以官方文件為準。

Q：免費可以做商業網站嗎？ A：可以，Pages 免費方案允許商業使用。

Q：怎麼做全端（表單、API）？ A：在 functions/ 目錄以檔案路由加入 Pages Functions，並透過 bindings 連接 D1 / KV / R2 等資源處理動態邏輯。

Q：Pages Functions 跟 Workers 是同一個東西嗎？ A：底層執行環境相同，Pages Functions 即是以 Workers 執行；其請求計入 Workers 的免費額度。

總結

核心要點：

Cloudflare Pages
├── 定位：Git 驅動的前端 / 全端架站平台
├── 靜態：請求免費、頻寬無上限、免費可商用
├── 動態：Pages Functions（底層 Workers，計入 Workers 額度）
├── 部署：push → build → 邊緣部署；Production / Preview；可 rollback
└── 額度：500 builds/月、同時 1 建置、每專案 100 自訂網域

Pages vs Workers 選用決策：

• 以網站 / 前端為主 → Pages
• 以邊緣函式運算為主 → Workers
• 前端為主、需少量 API → Pages + Pages Functions

快速參考：

npm i -g wrangler
wrangler pages deploy ./dist

記憶口訣：「靜態走 Pages，運算走 Workers；Functions 借 Workers 的力。」

系列總覽：Cloudflare 系列總覽

建立日期：2026-06-08 / 最後更新：2026-06-08