跳轉至

建立 2026-11-22 更新 2026-11-22

Pages Functions

Pages Functions 讓 Cloudflare Pages 專案除了靜態檔案,還能在伺服器端執行程式碼,用來撰寫 API、處理表單、驗證登入或改寫回應。只要在專案根目錄建立 functions/ 資料夾,檔案路徑就會自動對應成網址路由。Pages Functions 底層就是 Cloudflare Workers,可以使用 KV、D1、R2 等儲存服務。

檔案路徑如何對應網址?

my-site/
├── public/                  # 靜態檔案(輸出目錄)
└── functions/
    ├── api/
    │   ├── hello.js         → /api/hello
    │   └── users/
    │       └── [id].js      → /api/users/123(id = "123")
    └── _middleware.js       → 所有請求都會先經過
  • [id].js:中括號代表動態參數,可從 context.params.id 取得。
  • [[path]].js:雙中括號代表匹配多層路徑。
  • _middleware.js:中介層,適合做驗證、記錄、加標頭。

第一個 Function

functions/api/hello.js
export function onRequestGet(context) {
  const name = new URL(context.request.url).searchParams.get("name") ?? "訪客";
  return Response.json({ message: `你好,${name}!` });
}

部署後開啟 https://my-site.pages.dev/api/hello?name=Cloudflare 就會得到 JSON 回應。

處理函式的名稱決定對應的 HTTP 方法:onRequest(全部方法)、onRequestGet、onRequestPost、onRequestPut、onRequestDelete 等。

處理表單 POST

functions/api/contact.js
export async function onRequestPost({ request, env }) {
  const form = await request.formData();
  const email = form.get("email");
  if (!email) {
    return new Response("缺少 email", { status: 400 });
  }
  // 存入 KV:env.CONTACTS 是在設定中綁定的 KV 命名空間
  await env.CONTACTS.put(`contact:${Date.now()}`, JSON.stringify({ email }));
  return Response.redirect(new URL("/thanks", request.url), 303);
}

如何使用環境變數與儲存服務?

context.env 包含所有綁定(Bindings):

  • 環境變數/Secret:在 Pages 專案 Settings → Variables and Secrets 設定,程式中用 env.API_KEY 讀取。
  • KV、D1、R2 等儲存:在 Settings → Bindings 新增,指定變數名稱(例如 CONTACTS)與要綁定的資源。也可以寫在 wrangler.jsonc。
wrangler.jsonc
{
  "name": "my-site",
  "pages_build_output_dir": "./public",
  "compatibility_date": "2026-11-01",
  "kv_namespaces": [
    { "binding": "CONTACTS", "id": "你的 KV namespace ID" }
  ]
}

儲存服務的差異請參考 KV、D1 與 R2。

本機開發

npx wrangler pages dev public

Wrangler 會在本機模擬 Pages 與 Functions 的執行環境,KV、D1 等綁定也會在本機建立模擬資料。

計費要注意什麼?

靜態檔案請求免費且不限量;Functions 的呼叫次數與 Workers 共用額度(免費方案每日 10 萬次請求)。只有需要動態處理的路徑才放 Function,靜態內容不要經過 Function。

相關資料