Cloudflare Pages 部署排障全指南Gotchas 疑难清单与实战排查手册【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以 Cloudflare Deploy 技能仓库中 Cloudflare Pages 排障清单 为骨架系统梳理 Pages 与 Pages Functions 部署、运行时最常踩的坑从 Functions 404、静态资源失效、Bindings 不生效到中间件、_headers/_redirects、类型错误、本地开发、性能、Smart Placement 与远程绑定问题并给出可复制的修复命令与源码级佐证。读完你将获得一张可直接对照执行的排障决策表并能结合 configuration.md 与 api.md 快速定位问题根因。一、排障思路症状 → 原因 → 解决Pages 项目的绝大多数故障都集中在四类根因构建输出与配置不匹配、路由文件_routes.json误配、绑定Bindings未对齐、框架适配器状态不明。仓库中的 gotchas.md 正是按症状—原因—解决三段式组织本文沿此脉络逐项展开并补充底层配置与源码佐证。二、Functions 不执行端点 404 或方法不触发症状Function 端点返回 404或请求根本没进入函数代码。常见原因三选一或叠加出现_routes.json把目标路径写进了exclude导致请求被当作静态资源处理函数文件扩展名错误如写成.jsx/.tsxPages Functions 只识别.js/.tsFunctions 目录没有位于构建输出根目录pages_build_output_dir之下。解决步骤检查 _routes.json默认位于构建输出目录内确认目标路径未被exclude命中。注意exclude优先级高于include且 Functions 是按计量计费的把静态资源排除在外同时是省钱手段将函数文件重命名为.ts/.js后缀核对wrangler.jsonc中的pages_build_output_dir如./dist确认/functions目录位于该输出目录内。从 文件路由规则 看/functions/api/users.ts会映射为/api/users[id].ts对应:id单段参数[[path]].ts对应多段 catchall——文件位置即路由目录层级错位必然导致 404。三、静态资源 404文件无法访问症状CSS/JS/图片等静态文件返回 404。常见原因构建输出目录配置错误产物没落到正确位置Functions 抢占了静态请求路由过宽把静态路径也纳入了函数处理使用 Advanced Mode_worker.js时代码里缺少env.ASSETS.fetch()回退逻辑。解决步骤核对 Dashboard 构建设置或wrangler.jsonc中的输出目录确认dist产物完整在 _routes.json 的exclude中加入静态资源模式例如/build/*、/static/*、/*.{ico,png,jpg,css,js}若使用 Advanced Mode必须在_worker.js中调用env.ASSETS.fetch(request)兜底静态资源。仓库给出的标准骨架如下// functions/_worker.js export default { async fetch(request, env, ctx) { const url new URL(request.url); // 自定义路由 if (url.pathname.startsWith(/api/)) { return new Response(API response); } // 必须兜底服务静态资源 return env.ASSETS.fetch(request); } };详见 pages/api.md 与 pages-functions/api.md。四、Bindings 不生效env.BINDING为 undefined 或直接报错症状env.KV、env.DB等绑定取不到值或运行时抛错。常见原因wrangler.jsonc存在语法错误注意该文件是 JSONC允许注释绑定 ID 配错如 KV namespace ID、D1database_id本地缺少.dev.vars本地 Secret/Var 依赖它类型定义与实际配置不同步TypeScript 下表现尤为明显。解决步骤校验wrangler.jsonc语法参考 configuration.md 中的完整示例核对每种绑定的键名kv_namespaces、d1_databases、r2_buckets、durable_objects.bindings、services、queues.producers、vectorize、ai.binding等确认各绑定 ID 与云端资源一致本地开发创建.dev.vars切勿提交到版本库# .dev.vars (never commit) SECRET_KEYlocal-secret-key API_TOKENdev-token-123重新生成类型npx wrangler types。绑定名称是大小写敏感的配置键名与代码中的env.X必须严格一致这也是 pages-functions/gotchas.md 特别强调的常见误配点。五、构建失败部署在 Build 阶段挂掉症状Dashboard 上 Deployments 记录显示构建失败。常见原因构建命令或输出目录配错Node 版本不兼容本地能过、CI 不过构建期缺少环境变量如NEXT_PUBLIC_*超过 20 分钟构建超时内存不足OOM。解决步骤打开Dashboard → Deployments → Build log查看具体报错核对构建设置中的 build command / output directory在仓库根目录添加.nvmrc固定 Node 版本避免环境漂移为构建期补充所需环境变量优化构建裁剪依赖、减小体积以规避超时与 OOM。限额参考构建时长上限 20 分钟单次部署文件数上限 20,000单文件 25MB详见下文限额表。六、中间件不执行_middleware.ts未生效症状写在中间件里的鉴权、加头、错误处理逻辑完全没有跑。常见原因文件名不对必须是带下划线前缀的_middleware.ts注意前缀下划线没有导出onRequest或onRequest数组处理链断裂既没调用next()也没返回Response导致请求悬空。解决步骤将文件重命名为functions/_middleware.ts作用域为全站或functions/api/_middleware.ts仅作用于/api/*确保导出处理器// functions/_middleware.ts —— 单中间件 export const onRequest: PagesFunction async (context) { const response await context.next(); response.headers.set(X-Custom-Header, value); return response; }; // 链式中间件按数组顺序执行 export const onRequest [errorHandler, auth];每个中间件最终必须return context.next()放行或直接返回Response短路。context.data是中间件间共享状态的载体例如鉴权中间件可以把用户信息写入context.data.userId供下游函数读取这是 pages/api.md 中的标准做法。七、_headers/_redirects不生效症状配置的响应头或重定向规则没有生效。常见原因这两个文件只作用于静态资源由 Functions 生成的响应不会经过它们同名路径存在 Functions 路由时Functions 优先静态规则被覆盖文件存在语法错误超出限额_headers最多 100 条规则_redirects最多 2,100 条2,000 静态 100 动态。解决步骤语法自查。_redirects支持状态码、splat 通配符与占位符/old-page /new-page 301 # 301 重定向 /blog/* /news/:splat 301 # Splat 通配符 /users/:id /members/:id 301 # 占位符 /api/* /api-v2/:splat 200 # 代理不重定向_headers按路径分组声明/secure/* X-Frame-Options: DENY X-Content-Type-Options: nosniff /api/* Access-Control-Allow-Origin: * /static/* Cache-Control: public, max-age31536000, immutable确认目标资源是静态文件而非 Functions 输出若需要给 Functions 响应加头应直接在函数返回的Response对象上设置 header例如在中间件里response.headers.set(...)。八、TypeScript 类型错误env一堆红线症状Function 代码里env.X报类型错误。常见原因类型文件未生成手写的Envinterface 与wrangler.jsonc中的绑定不一致。解决步骤生成类型文件并固定输出位置npx wrangler types --path./functions/types.d.ts在functions/tsconfig.json中把types指向生成的文件确保Envinterface 与实际绑定对应。以 D1 KV 为例import type { PagesFunction } from cloudflare/workers-types; interface Env { DB: D1Database; KV: KVNamespace; } export const onRequestGet: PagesFunctionEnv async ({ env }) { const user await env.DB.prepare(SELECT * FROM users WHERE id ?).bind(123).first(); return Response.json(user); };九、本地开发问题dev server 起不来或绑定异常症状wrangler pages dev报错或本地绑定行为与线上不一致。常见原因端口被占用绑定未传入本地 dev server本地 HTTP 与线上 HTTPS 的协议差异导致行为不一致例如安全 cookie、Referer判断。解决步骤指定端口启动npx wrangler pages dev ./dist --port3000通过 CLI 传入绑定npx wrangler pages dev ./dist --kv KV --d1 DBlocal-db-id或在wrangler.jsonc中配置本地环境会自动读取.dev.vars留意 HTTP/HTTPS 差异涉及协议判断的逻辑在本地调试时单独验证。仓库 configuration.md 给出了完整的本地开发命令族包括持久化状态与代理模式SSR 框架用# 基础 npx wrangler pages dev ./dist # 带绑定 npx wrangler pages dev ./dist --kv KV --d1 DBlocal-db-id # 远程绑定生产数据慎用 npx wrangler pages dev ./dist --remote # 状态持久化 npx wrangler pages dev ./dist --persist-to./.wrangler/state/v3 # 代理模式SSR 框架 npx wrangler pages dev -- npm run dev十、性能问题响应慢或触发 CPU 限额症状请求响应缓慢或日志出现 Request exceeded CPU limit。常见原因Functions 被不必要地调用在静态资源上路由过宽冷启动冷启动延迟超出 CPU 限额Free 10ms/reqWorkers Paid 30ms/req打包体积过大。解决步骤通过_routes.json的exclude把静态资源排除在 Functions 之外——静态请求免费且不占 CPU 配额优化热路径减少同步阻塞、合并 I/O、优先用await并发保持 bundle 1MBFree 脚本大小上限 1MB 压缩后Paid 10MB必要时做 tree-shaking、动态 import、代码分割。参考 pages-functions/gotchas.md 的最佳实践用 KV 做缓存、D1 做关系数据、R2 放大文件并设置合理的Cache-Control头。十一、框架适配哪些能用、哪些已废弃⚠️ 已废弃框架2024 年后无维护Next.js官方适配器cloudflare/next-on-pages已废弃且不再维护。问题2024 年后无更新与 Next.js 15 不兼容缺少 App Router 特性原因Cloudflare 已停止官方支持社区 fork 存在但能力有限解决方案推荐改用 Vercel 托管Next.js 官方宿主进阶基于 Workers 自定义适配器自托管复杂且不受支持迁移切换到 SvelteKit/Nuxt开发体验相似Pages 完整支持。Remix官方适配器remix-run/cloudflare-pages已废弃。问题Remix 团队停止维护与 Remix v2 存在兼容性问题原因Remix 团队废弃了全部框架适配器解决方案推荐迁移到 SvelteKit类似的文件路由更好的 DX备选使用 Astro静态优先、可选 SSR兜底继续使用废弃适配器但无后续支持。✅ 受支持框架2026 状态框架配置方式绑定访问入口SvelteKitsveltejs/adapter-cloudflaresvelte.config.js设platform: cloudflareserver load 函数中的platform.envAstro内置 Cloudflare 适配器Astro.locals.runtime.envNuxtnuxt.config.ts设nitro.preset: cloudflare-pagesevent.context.cloudflare.envQwik / Solid Start内置或官方 Cloudflare 适配器参见各框架文档框架集成代码示例详见 patterns.md例如 SvelteKit 的page.server.ts中platform.env.DB.prepare(...)、Astro 前端组件中的Astro.locals.runtime.env、Nuxt 的event.context.cloudflare.env.DB。十二、调试技巧日志与实时追踪在函数代码中埋点打印请求、环境与路由参数// 记录请求详情 console.log(Request:, { method: request.method, url: request.url }); console.log(Env:, Object.keys(env)); console.log(Params:, params);实时查看线上日志npx wrangler pages deployment tail --project-namemy-project还可以按状态过滤如只看错误npx wrangler pages deployment tail --status error若需要定位生产环境下的类型/堆栈问题可在wrangler.jsonc中开启源码映射{ upload_source_maps: true }。十三、Smart Placement 疑难Smart Placement 会根据流量模式自动优化函数执行位置配置方式见 configuration.md其排障细节与 smart-placement/gotchas.md 一致常见问题如下。冷启动延迟增加问题开启 Smart Placement 后首批请求变慢原因系统处于学习流量模式的初始优化期解决部署后 24–48 小时内属预期行为持续监控延迟趋势即可。响应时间不稳定问题初始部署期间各请求延迟波动明显原因Smart Placement 正在测试不同执行位置以寻找最优落点解决学习期属正常现象流量模式形成后约 1–2 天会趋于稳定。开启后无性能提升问题启用 Smart Placement 但延迟没有下降原因流量在全球均匀分布或不存在数据本地性约束如数据都在单一中心区域解决Smart Placement 对数据集中D1/DO或区域集中流量最有效若无收益直接关闭。显式关闭{ placement: { mode: off } } // 或直接删除 placement 字段效果相同关键限制仅影响 fetch 处理器Smart Placement只对fetch处理器生效Service Bindings 的 RPC 方法WorkerEntrypoint完全不受影响因为 RPC 绕过了fetch入口。需要优化后端 RPC 延迟时应改用 fetch 形式的 Service Binding。此外 Smart Placement 需要 Wrangler 2.20.0 且仅在生产环境生效本地wrangler dev不生效需用wrangler deploy --env staging验证分析期最长 15 分钟期间会路由约 1% 请求不做优化用于基线对比。十四、远程绑定--remote注意事项本地开发通过--remote直连生产绑定方便验证但代价是直写生产数据。误改生产数据问题本地--remote开发意外修改了生产库/KV原因远程绑定直连生产资源写入是真实的解决--remote仅用于读为主的调试测试请单独创建 preview 环境开发期间绝不用--remote做写操作。认证错误问题npx wrangler pages dev --remote报 Unauthorized 或认证错误原因未登录、会话过期或账号权限不足解决npx wrangler login重新认证确认账号对项目和绑定有访问权限核对绑定 ID 与生产配置一致。本地开发变慢问题--remote下本地 dev server 变慢原因每个请求都会网络调用生产绑定解决开发期用本地绑定仅在最终验证时使用--remote。十五、常见错误速查表错误信息原因解决Module not found依赖未打包或构建输出错误检查构建输出目录确保依赖被打包Binding not found绑定未配置或类型不同步核对 wrangler.jsonc运行npx wrangler typesRequest exceeded CPU limit代码执行过慢或计算密集优化热路径升级 Workers PaidScript too large打包体积超限Tree-shake、动态 import、代码分割Too many subrequests超过单请求 50 次子请求上限合并或减少 fetch 调用KV key not foundKey 不存在或 namespace 配错核对 namespace 与环境是否匹配D1 errordatabase_id错误或缺少迁移核对配置运行wrangler d1 migrations list补充几个 Function 侧的典型报错pages-functions/gotchas.md函数超时通常是同步阻塞或漏写await所有 I/O 必须 async/await后台任务用ctx.waitUntil()生产环境 Secret 缺失.dev.vars仅本地生效生产 Secret 必须通过 Dashboard 或wrangler pages secret put单独设置echo value | npx wrangler pages secret put SECRET_KEY --project-namemy-project npx wrangler pages secret list --project-namemy-project npx wrangler pages secret delete SECRET_KEY --project-namemy-project十六、限额参考2026 年 1 月资源FreePaidFunctions 请求100k/天无限按量计费Function CPU 时间10ms/req30ms/reqWorkers PaidFunction 内存128MB128MB脚本体积1MB压缩10MB压缩子请求数50/req1,000/reqWorkers Paid部署次数500/月5,000/月单次部署文件数20,00020,000单文件大小25MB25MB构建时长20min20min重定向规则2,1002,000 静态 100 动态同左响应头规则100100路由规则_routes.json100每条 ≤100 字符100提示Functions 使用 Workers 运行时Workers Paid 计划可提升上述限额Free 计划足以覆盖大多数项目静态请求永远免费不占用 Functions 配额。命中 CPU 限额时优先优化热路径或升级 Workers Paid。十七、获取帮助查阅 Cloudflare Pages 官方文档在 Cloudflare 社区 Discord 的 #functions 频道检索浏览 Workers Examples 官方示例库查阅所用框架的适配器/文档。若需要在本仓库内继续深入建议按如下顺序阅读同目录系列文档pages/README.md总览与快速开始→ pages/configuration.mdwrangler.jsonc、绑定、静态配置文件→ pages/api.mdFunctions API、路由、上下文→ pages/patterns.md常见实现模式函数侧细节可对照 pages-functions/ 系列文档。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
