【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载本篇技术指南以 autoskills 仓库中 cloudflare-deploy 技能包 提供的 Pages Functions 参考文档为核心系统讲解 Cloudflare Pages Functions 的完整 APIEventContext上下文对象、onRequest系列处理器、全部平台绑定KV / D1 / R2 / Durable Objects / Workers AI / Service Bindings / Analytics Engine 等以及高级模式env.ASSETS。读完本文你将能够熟练编写带完整类型约束的 Pages Functions 后端、正确配置wrangler.jsonc绑定、并理解如何把静态站点与边缘计算无缝结合。Pages Functions 与EventContext全景Cloudflare Pages Functions 是运行在 Workers 运行时上的服务端函数采用文件即路由file-based routing的方式为静态站点提供动态后端能力。每个函数导出onRequest系列处理器接收统一的EventContext上下文对象从中读取请求、环境变量、路由参数与中间件共享状态。EventContext接口完整定义如下取自 api.mdinterface EventContextEnv any { request: Request; // Incoming request functionPath: string; // Request path waitUntil(promise: Promiseany): void; // Background tasks (non-blocking) passThroughOnException(): void; // Fallback to static on error next(input?: Request | string, init?: RequestInit): PromiseResponse; env: Env; // Bindings, vars, secrets params: Recordstring, string | string[]; // Route params ([user] or [[catchall]]) data: any; // Middleware shared state }各字段职责如下request入站请求对象可直接调用ctx.request.json()、ctx.request.headers、ctx.request.formData()等方法解析请求内容functionPath当前函数对应的请求路径用于路由逻辑判断waitUntil(promise)注册后台任务响应返回后继续执行不阻塞主链路——适合埋点统计、异步清理、Webhook 推送等场景passThroughOnException()函数抛错时回退到静态资源服务保证站点可用性next()调用下一个中间件或处理器返回其Response可传入新的Request或路径覆盖请求env环境上下文承载全部绑定KV、D1、R2、Secrets、Vars 等params路由参数单段参数[user]为string多段捕获参数[[catchall]]为string[]data中间件之间共享的状态对象例如鉴权中间件可以把解析出的用户信息写入ctx.data.user供后续处理器读取。类型提示EventContext是泛型接口通过PagesFunctionEnv泛型将env的类型约束为自定义的Env接口。TypeScript 类型可通过npx wrangler types从wrangler.jsonc自动生成详见下文「TypeScript 类型设置」。处理器Handlers通用与按 HTTP 方法分派Pages Functions 的核心导出约定是onRequest系列函数。通用处理器onRequest作为所有 HTTP 方法的兜底而方法专属处理器onRequestGet、onRequestPost等优先级更高命中时覆盖通用处理器。// Generic (fallback for any method) export async function onRequest(ctx: EventContext): PromiseResponse { return new Response(Any method); } // Method-specific (takes precedence over generic) export async function onRequestGet(ctx: EventContext): PromiseResponse { return Response.json({ message: GET }); } export async function onRequestPost(ctx: EventContext): PromiseResponse { const body await ctx.request.json(); return Response.json({ received: body }); } // Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions完整的方法处理器清单还包括onRequestPut、onRequestPatch、onRequestDelete、onRequestHead与onRequestOptions。这一约定让同一个文件可以按 HTTP 方法拆分逻辑——例如onRequestOptions天然适合实现 CORS 预检响应而onRequestPost专注处理表单与 JSON 提交。实战模式参见 patterns.md 中的 CORS 中间件示例。文件即路由与动态参数处理器文件放在/functions目录下目录结构即路由结构详见 pages-functions README/functions ├── index.js → / ├── api.js → /api ├── users/ │ ├── index.js → /users/ │ ├── [user].js → /users/:user │ └── [[catchall]].js → /users/* └── _middleware.js → runs on all routes路由规则index.js映射到目录根路径尾部斜杠可选具体路由优先于捕获路由无函数命中时回退到静态资源。动态路由通过params读取// /functions/users/[user].js export function onRequest(context) { return new Response(Hello ${context.params.user}); } // Matches: /users/nevi → params.user nevi// /functions/users/[[catchall]].js export function onRequest(context) { return new Response(JSON.stringify(context.params.catchall)); } // Matches: /users/nevi/foobar → [nevi, foobar][[catchall]]多段捕获参数在params中表现为数组覆盖/users/*任意深度路径。绑定Bindings速查表绑定是把 Worker 运行时与 Cloudflare 平台资源连接起来的桥梁通过env对象访问在wrangler.jsonc中配置、由wrangler types生成类型。以下速查表汇总了 Pages Functions 可用的全部绑定类型取自 api.mdBinding TypeInterfaceConfig KeyUse CaseKVKVNamespacekv_namespacesKey-value cache, sessions, configD1D1Databased1_databasesRelational data, SQL queriesR2R2Bucketr2_bucketsLarge files, user uploads, assetsDurable ObjectsDurableObjectNamespacedurable_objects.bindingsStateful coordination, websocketsWorkers AIAiai.bindingLLM inference, embeddingsVectorizeVectorizeIndexvectorizeVector search, embeddingsService BindingFetcherservicesWorker-to-worker RPCAnalytics EngineAnalyticsEngineDatasetanalytics_engine_datasetsEvent logging, metricsEnvironment VarsstringvarsNon-sensitive config选择建议结合 bindings README需要键值缓存 / 会话 / 小规模配置25MB→ KV需要关系型 SQL 数据→ D1需要大文件、用户上传、S3 兼容对象存储→ R2需要有状态协调、实时 WebSocket 状态→ Durable Objects需要LLM 推理与向量嵌入→ Workers AI / Vectorize需要Worker 间 RPC 调用→ Service Binding需要事件日志与自定义指标→ Analytics Engine。各类绑定的代码实战以下代码示例均来自 api.md展示了每种绑定的最小可用写法。KV键值缓存与会话interface Env { KV: KVNamespace; } export const onRequest: PagesFunctionEnv async (ctx) { await ctx.env.KV.put(key, value, { expirationTtl: 3600 }); const val await ctx.env.KV.get(key, { type: json }); const keys await ctx.env.KV.list({ prefix: user: }); return Response.json({ val }); };put支持expirationTtlTTL 秒数实现自动过期get通过{ type: json }自动反序列化list({ prefix })按前缀枚举键——适合实现user:前缀的会话列表。KV 也是 KV 型限流rate:${ip}计数 TTL 重置的天然载体见 patterns.md 的 Rate Limiting 示例。D1关系型 SQLinterface Env { DB: D1Database; } export const onRequest: PagesFunctionEnv async (ctx) { const user await ctx.env.DB.prepare(SELECT * FROM users WHERE id ?).bind(123).first(); return Response.json(user); };D1 采用 SQLite 兼容的prepare(...).bind(...)链式 APIprepare编译 SQLbind绑定占位参数.first()取首行。批量操作可继续使用.all()、.run()等方法配合事务可完成完整 CRUD。R2对象存储与文件上传interface Env { BUCKET: R2Bucket; } export const onRequest: PagesFunctionEnv async (ctx) { const obj await ctx.env.BUCKET.get(file.txt); if (!obj) return new Response(Not found, { status: 404 }); await ctx.env.BUCKET.put(file.txt, ctx.request.body); return new Response(obj.body); };get读取对象不存在时返回 404put把请求体ctx.request.body流式直接写入桶。结合 patterns.md 的 multipart 上传示例可完成完整的文件上传闭环export async function onRequestPost(ctx) { const ct ctx.request.headers.get(content-type) || ; if (ct.includes(application/json)) return Response.json(await ctx.request.json()); if (ct.includes(multipart/form-data)) { const file (await ctx.request.formData()).get(file) as File; await ctx.env.BUCKET.put(file.name, file.stream()); return Response.json({ uploaded: file.name }); } }Durable Objects有状态协调interface Env { COUNTER: DurableObjectNamespace; } export const onRequest: PagesFunctionEnv async (ctx) { const stub ctx.env.COUNTER.get(ctx.env.COUNTER.idFromName(global)); return stub.fetch(ctx.request); };通过idFromName(global)生成确定性 ID 获取单例 stub再把请求fetch转发给 Durable Object 处理——这是计数器、房间同步、WebSocket 长连接等有状态场景的标准接入方式。Workers AILLM 推理interface Env { AI: Ai; } export const onRequest: PagesFunctionEnv async (ctx) { const resp await ctx.env.AI.run(cf/meta/llama-3.1-8b-instruct, { prompt: Hello }); return Response.json(resp); };AI.run(model, input)直接调用 Cloudflare 边缘侧的模型推理模型以cf/...命名空间标识。Pages Functions 由此可以在边缘完成文本生成、嵌入等 AI 能力。Service Bindings 与环境变量interface Env { AUTH: Fetcher; API_KEY: string; } export const onRequest: PagesFunctionEnv async (ctx) { // Service binding: forward to another Worker return ctx.env.AUTH.fetch(ctx.request); // Environment variable return Response.json({ key: ctx.env.API_KEY }); };Service Binding 以Fetcher类型暴露调用env.AUTH.fetch(request)即可把请求转发给另一个 Worker实现 Worker 间 RPC环境变量在Env接口中声明为string通过ctx.env.API_KEY读取非敏感配置。高级模式env.ASSETS与_worker.jsPages Functions 的另一种形态是「高级模式」在项目根目录放置_worker.js彻底接管请求处理替代/functions目录。此时静态资源通过env.ASSETS.fetch()访问interface Env { ASSETS: Fetcher; KV: KVNamespace; } export default { async fetch(request: Request, env: Env): PromiseResponse { const url new URL(request.url); if (url.pathname.startsWith(/api/)) { return Response.json({ data: await env.KV.get(key) }); } return env.ASSETS.fetch(request); // Fallback to static } } satisfies ExportedHandlerEnv;这个模式实现了「API 与静态站点共存」的经典分流/api/*前缀的请求走动态逻辑此处读取 KV其余请求回落到env.ASSETS.fetch()交给静态资源服务。satisfies ExportedHandlerEnv提供完整类型检查。何时选择高级模式见 patterns.md已有现成 Worker需要迁移到 Pages 保留复杂路由使用 Next.js / SvelteKit / Remix 等框架构建产物自动生成_worker.js需要export default { fetch(req, env) }形态的精细路由控制。TypeScript 类型设置与 wrangler.jsonc 绑定配置生成类型npx wrangler types会读取wrangler.jsonc生成worker-configuration.d.ts其中的Env接口覆盖所有已配置绑定此方式已取代被弃用的cloudflare/workers-types包npx wrangler types// functions/api.ts export const onRequest: PagesFunctionEnv async (ctx) { // ctx.env.KV, ctx.env.DB, etc. are fully typed return Response.json({ ok: true }); };不生成类型时也可手工声明Env接口KVNamespace、D1Database等类型名与上表一致interface Env { KV: KVNamespace; DB: D1Database; API_KEY: string; } export const onRequest: PagesFunctionEnv async (ctx) { /* ... */ };wrangler.jsonc 完整示例以下配置文件示例来自 configuration.md一次性声明了全部常用绑定{ $schema: ./node_modules/wrangler/config-schema.json, name: my-pages-app, pages_build_output_dir: ./dist, compatibility_date: 2025-01-01, compatibility_flags: [nodejs_compat], vars: { API_URL: https://api.example.com }, kv_namespaces: [{ binding: KV, id: abc123 }], d1_databases: [{ binding: DB, database_name: prod-db, database_id: xyz789 }], r2_buckets: [{ binding: BUCKET, bucket_name: my-bucket }], durable_objects: { bindings: [{ name: COUNTER, class_name: Counter, script_name: counter-worker }] }, services: [{ binding: AUTH, service: auth-worker }], ai: { binding: AI }, vectorize: [{ binding: VECTORIZE, index_name: my-index }], analytics_engine_datasets: [{ binding: ANALYTICS }] }关键字段说明pages_build_output_dirPages 构建产物目录如./dist函数目录与静态资源都源于此compatibility_date运行时兼容性日期compatibility_flags中的nodejs_compat开启 Node.js API 兼容绑定字段binding/name为env中的访问名大小写敏感必须与代码中的ctx.env.X完全一致KV 需idD1 需database_namedatabase_idR2 需bucket_nameService Binding 需service目标 Worker 名Durable Objects 需class_name与script_name。环境覆盖Environment Overrides配置按「顶层 → 本地开发、env.preview→ 预览、env.production→ 生产」三级生效{ vars: { API_URL: http://localhost:8787 }, env: { production: { vars: { API_URL: https://api.example.com } } } }注意vars、kv_namespaces、d1_databases等字段不可继承——若在某个环境覆盖了其中任一字段必须在该环境内完整重定义全部相关字段否则会丢失配置。本地密钥与生产密钥.dev.vars仅用于本地开发不会被部署# .dev.vars (add to .gitignore) SECRET_KEYmy-secret-value通过ctx.env.SECRET_KEY读取。生产环境的密钥必须显式写入echo value | npx wrangler pages secret put SECRET_KEY --project-namemy-app静态配置文件Pages 支持三个静态配置文件定制行为_routes.json— 自定义路由规则{ version: 1, include: [/api/*], exclude: [/static/*] }可精确控制哪些路径交给函数执行、哪些回退静态_headers— 静态资源响应头/static/*下的Cache-Control: public, max-age31536000_redirects— 重定向规则/old /new 301。中间件、后台任务与常见模式中间件与鉴权_middleware.js可放在/functions根目录全局生效或子目录局部生效导出onRequest链式处理// functions/_middleware.js (global) or functions/users/_middleware.js (scoped) export async function onRequest(ctx) { try { return await ctx.next(); } catch (err) { return new Response(err.message, { status: 500 }); } } // Chained: export const onRequest [errorHandler, auth, logger]; // Auth async function auth(ctx: EventContextEnv) { const token ctx.request.headers.get(authorization)?.replace(Bearer , ); if (!token) return new Response(Unauthorized, { status: 401 }); const session await ctx.env.KV.get(session:${token}); if (!session) return new Response(Invalid, { status: 401 }); ctx.data.user JSON.parse(session); return ctx.next(); }要点中间件必须调用ctx.next()才会继续执行后续链路export const onRequest [fn1, fn2, fn3]数组形式可串联多个中间件鉴权结果通过ctx.data传递给下游处理器。后台任务waitUntil响应发出后继续执行的异步工作适合埋点、清理与 Webhookexport async function onRequest(ctx: EventContextEnv) { const res Response.json({ success: true }); ctx.waitUntil(ctx.env.KV.put(last-visit, new Date().toISOString())); ctx.waitUntil(Promise.all([ ctx.env.ANALYTICS.writeDataPoint({ event: view }), fetch(https://webhook.site/..., { method: POST }) ])); return res; // Returned immediately }waitUntil注册的 Promise 不阻塞主响应但保证在请求生命周期内完成且可用Promise.all并行聚合多个任务。CORS、限流与缓存CORS 中间件onRequestOptions直接返回预检响应 主处理器为响应注入头const cors { Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET, POST }; export async function onRequestOptions() { return new Response(null, { headers: cors }); } export async function onRequest(ctx) { const res await ctx.next(); Object.entries(cors).forEach(([k, v]) res.headers.set(k, v)); return res; }KV 限流基于CF-Connecting-IP计数 TTL 过期async function rateLimit(ctx: EventContextEnv) { const ip ctx.request.headers.get(CF-Connecting-IP) || unknown; const count parseInt(await ctx.env.KV.get(rate:${ip}) || 0); if (count 100) return new Response(Rate limited, { status: 429 }); await ctx.env.KV.put(rate:${ip}, (count 1).toString(), { expirationTtl: 3600 }); return ctx.next(); }Cache API 缓存先查caches.default未命中时生成响应并waitUntil写入缓存配合Cache-Control头控制有效期。本地开发、部署与调试本地开发与部署命令# Dev server npx wrangler pages dev ./dist # With bindings npx wrangler pages dev ./dist --kvKV --d1DBdb-id --r2BUCKET # Durable Objects (2 terminals) cd do-worker npx wrangler dev cd pages-project npx wrangler pages dev ./dist --do COUNTERCounterdo-worker # Deploy npx wrangler pages deploy ./dist npx wrangler pages deploy ./dist --branch preview # Download config npx wrangler pages download config my-project--branch preview可部署到预览环境Durable Objects 联调需要在两个终端分别启动 DO Worker 与 Pages 项目并通过--do参数建立映射。调试技巧// Console logging export async function onRequest(ctx) { console.log(Request:, ctx.request.method, ctx.request.url); const res await ctx.next(); console.log(Status:, res.status); return res; }# Stream real-time logs npx wrangler pages deployment tail npx wrangler pages deployment tail --status error// Source maps (wrangler.jsonc) { upload_source_maps: true }wrangler pages deployment tail可实时流式查看线上日志--status error过滤错误开启upload_source_maps可定位压缩后堆栈。常见问题排查表SymptomLikely CauseSolutionFunction not invokingWrong/functionslocation, wrong extension, or_routes.jsonexcludes pathCheckpages_build_output_dir, use.js/.ts, verify_routes.jsonctx.env.BINDINGundefinedBinding not configured or name mismatchAdd towrangler.jsonc, verify exact name (case-sensitive), redeployTypeScript errors onctx.envMissing type definitionRunwrangler typesor defineinterface Env {}Middleware not runningWrong filename/location or missingctx.next()Name exactly_middleware.js, exportonRequest, callctx.next()Secrets missing in production.dev.varsnot deployed.dev.varsis local only - set production secrets via dashboard orwrangler secret putType mismatch on bindingWrong interface typeSee bindings table for correct typesKV key not found but existsKey in wrong namespace or envVerify namespace binding, check preview vs production envFunction times outSynchronous wait or missingawaitAll I/O must be async/await, usectx.waitUntil()for background tasks排查要点归纳函数不触发先查_routes.json与构建目录ctx.env.X为undefined优先核对wrangler.jsonc中的绑定名大小写敏感中间件不执行检查文件名是否恰为_middleware.js且调用了ctx.next()生产环境密钥缺失是因为.dev.vars不部署需改用wrangler pages secret put。限制与最佳实践资源限制ResourceFreePaidCPU time10ms50msMemory128 MB128 MBScript size10 MB compressed10 MB compressedEnv vars5 KB per var, 64 max5 KB per var, 64 maxRequests100k/dayUnlimited ($0.50/million)另注意单个 Worker 的所有绑定类型合计最多 64 个见 bindings README。性能与安全最佳实践性能最小化依赖以减少冷启动按场景选型——KV 做缓存、D1 做关系型数据、R2 存大文件设置Cache-Control响应头数据库操作尽量批量优雅处理错误。安全绝不提交密钥.dev.vars加入.gitignore校验并清洗输入后再写库通过鉴权中间件保护接口配置 CORS 头按 IP 限流防滥用。迁移指南Workers → Pages Functions把export default { fetch(req, env) {} }改写为export function onRequest(ctx) { const { request, env } ctx; }复杂路由可改用_worker.js并通过env.ASSETS.fetch(request)服务静态文件。其他平台 → Pages文件即路由/functions/api/users.js对应/api/users动态路由用[param]而非:paramNode.js 依赖替换为 Workers API 或开启nodejs_compat标志。继续深入Pages Functions 路由与中间件总览配置与类型生成完整指南中间件、鉴权、CORS、限流与测试模式常见错误、调试与资源限制Cloudflare 部署技能包总览赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐Kindle 打不开你的书Calibre 免费搞定电子书格式转换与书库管理Kindle 打不开你的书Calibre 免费搞定电子书格式转换与书库管理 Calibre 是一款免费、开源的电子书管理工具一次装好就能覆盖格式转换、书库管桌面应用后端明日方舟 MAA 小助手新手指南日常一键长草5 分钟跑起来明日方舟 MAA 小助手新手指南日常一键长草5 分钟跑起来 每天登录《明日方舟》体力要刷、基建要换班、公招要刷、好友要访问——点完这些才能开始干别的。MA计算机视觉GUI自动化RPAtiny11builder 一步到位生成可启动的 Windows 11 精简镜像tiny11builder 一步到位生成可启动的 Windows 11 精简镜像 项目速览给什么 → 得什么 tiny11builder 用 PowerShe上一篇Profanity.dev监控与日志使用Redis追踪API使用情况终极指南下一篇70亿token喂出来的韩语大语言模型KoGPT-J-base训练数据集完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考