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。
本機開發
Wrangler 會在本機模擬 Pages 與 Functions 的執行環境,KV、D1 等綁定也會在本機建立模擬資料。
計費要注意什麼?
靜態檔案請求免費且不限量;Functions 的呼叫次數與 Workers 共用額度(免費方案每日 10 萬次請求)。只有需要動態處理的路徑才放 Function,靜態內容不要經過 Function。