尧图网站建设 
Cloudflare Workers for Platforms 排障手册常见错误、平台限制与极限参数全解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文是 Cloudflare Workers for Platforms下称 WfP多租户平台的权威排障参考完整梳理了动态分发命名空间Dispatch Namespace下最容易踩坑的 11 类运行时错误、4 类平台硬性限制平台限制、静态资源上传限制、API 速率限制、运行限制以及对应的修复方案。读完本文你将掌握 Worker not found、CPU 时间超限、绑定丢失、ES Module 部署失败等高频问题的根因定位与可复用的 TypeScript/curl 修复代码并能据此设计出可靠的限流重试、资源隔离与灰度发布方案。一、先理解排障的上下文WfP 的四组件架构所有下文错误与限制都发生在 WfP 特有的四组件架构中先明确各自职责才能精准定位问题出在哪一环Dispatch Namespace分发命名空间容纳无限量客户 Worker 的容器默认以 untrusted不信任模式隔离——无request.cf访问权、无共享缓存。Dynamic Dispatch Worker动态分发 Worker平台入口负责路由请求并强制执行平台逻辑鉴权、限额、校验。User Workers用户 Worker客户代码运行在隔离沙箱中通过 API 部署可选绑定 KV/D1/R2/Durable Objects 等。Outbound Worker出站 Worker可选拦截用户 Worker 的外部fetch()控制出站流量并记录子请求。请求流为Request → Dispatch Worker → env.DISPATCHER.get(customer) → User Worker外部 fetch 经 Outbound Worker→ Response → Dispatch Worker → Client。完整的架构与路由决策树可参考 README.md本节背景正是理解为什么会有这些 Gotchas的基础。二、常见错误逐一排查Common Errors1. Worker not found——请求了不存在的 Worker根因对命名空间中不存在的 Worker 调用了get()从而触发报错。解法捕获该错误并回退为 404 响应同时注意把意外错误重新抛出避免吞掉真实故障try { const userWorker env.DISPATCHER.get(workerName); return userWorker.fetch(request); } catch (e) { if (e.message.startsWith(Worker not found)) { return new Response(Worker not found, { status: 404 }); } throw e; // Re-throw unexpected errors }实践建议在 patterns.md 的路由模式中推荐先将主机名到 Worker 的映射存放在 KV例如键hostname:${hostname}由分发 Worker 查询后再get()这样能在调用前先判断 Worker 是否存在从源头减少 404 抖动。2. CPU time limit exceeded——CPU 时间超限根因用户 Worker 执行超出了为其配置的 CPU 时间限制。解法在分发 Worker 中捕获异常将违规记录到 Analytics Engine 并返回 429 响应同时考虑按客户套餐enterprise/pro/free调整限额try { return await userWorker.fetch(request); } catch (e) { if (e.message.includes(CPU time limit)) { // 记录违规便于计量与告警 env.ANALYTICS.writeDataPoint({ indexes: [workerName], blobs: [cpu_limit_exceeded], }); return new Response(CPU limit exceeded, { status: 429 }); } throw e; }配套的限额设置方式见 configuration.md 与 api.md通过env.DISPATCHER.get(workerName, {}, { limits: { cpuMs, subRequests } })在单次调用级覆盖限额patterns.md 给出了按套餐设限的完整实现例如 free 套餐{ cpuMs: 10, subRequests: 5 }、pro 套餐{ cpuMs: 20, subRequests: 20 }、enterprise 套餐{ cpuMs: 50, subRequests: 50 }。3. Hostname Routing Issues——主机名路由异常根因DNS 代理设置导致路由出现问题。解法改用*/*通配路由。该路由在任何 DNS 代理设置下均生效尤其能保证橙色到橙色orange-to-orange客户站点与你的 Workers 域都走 Cloudflare 代理路由的一致性。补充说明依据 patterns.md 的 O2O 行为表客户未使用 Cloudflare 时*/*与*.domain.com/*均可客户使用代理 CNAME 时必须在边缘调用 Worker只有*/*生效客户使用仅 DNS 的 CNAME 时任意路由均可。官方建议始终使用*/*通配路由以保持一致的 O2O 行为。4. Bindings Lost on Update——更新后绑定丢失根因更新 Worker 时未使用keep_bindings标志导致原有绑定被覆盖清除。解法在 API 请求中使用keep_bindings: true或按类型列出保留项以在更新期间保留既有绑定{ bindings: [{type: r2_bucket, name: STORAGE, bucket_name: new}], keep_bindings: [kv_namespace, d1] // Preserves existing bindings of these types }WfP 支持共 29 类绑定KV、D1、R2、Durable Objects、Analytics Engine、Service、Assets、Queue、Vectorize、Hyperdrive、Workflow、AI、Browser 等完整类型清单见 bindings 文档。5. Tag Filtering Not Working——标签过滤失效根因标签过滤条件中的特殊字符未做 URL 编码。解法对标签做 URL 编码例如tagsproduction%3Ayes并避免使用,与这类特殊字符。配套的标签操作命令见 configuration.md# 设置标签 curl -X PUT .../tags -d [customer-123, pro, production] # 按标签过滤注意 %3A 即 : 的 URL 编码 curl .../scripts?tagsproduction%3Ayes # 按标签批量删除 curl -X DELETE .../scripts?tagscustomer-123%3Ayes常用标签模式customer-123、free|pro|enterprise、production|staging。每个 Worker 最多 8 个标签标签化是批量操作列表、过滤、删除的基础。6. Deploy Failures with ES Modules——ES Module 部署失败根因ES Module 的上传格式不正确。解法使用 multipart 表单上传在 metadata 中指定main_module并将文件类型设为application/javascriptmodulecurl -X PUT \ https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME \ -H Authorization: Bearer $API_TOKEN \ -F metadata{main_module: worker.mjs};typeapplication/json \ -F worker.mjsworker.mjs;typeapplication/javascriptmoduleTypeScript SDK 的等价写法见 api.mdimport Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env.API_TOKEN }); const scriptFile new File([scriptContent], ${scriptName}.mjs, { type: application/javascriptmodule, }); await client.workersForPlatforms.dispatch.namespaces.scripts.update( namespace, scriptName, { account_id: accountId, metadata: { main_module: ${scriptName}.mjs }, files: [scriptFile], } );部署时建议在 metadata 中携带compatibility_date新项目使用当前日期避免因兼容性日期缺失导致运行时不兼容。7. Static Asset Upload Failed——静态资源上传失败根因哈希格式非法、令牌过期或编码不正确。解法需同时满足三条约束哈希必须是 SHA-256 的前 16 字节32 个十六进制字符必须在会话创建后 1 小时内完成上传必须在上传完成后 1 小时内完成 Worker 部署文件内容必须做 Base64 编码。配套的三步上传流程见 api.md# 1. 创建上传会话manifest 中的 hash 为 SHA-256 前 16 字节 curl -X POST .../scripts/$SCRIPT_NAME/assets-upload-session \ -H Authorization: Bearer $API_TOKEN \ -d { manifest: { /index.html: {hash: 08f1dfda4574284ab3c21666d1ee8c7d4, size: 1234} } } # 返回jwt, buckets # 2. 上传文件Base64 编码携带上传 JWT curl -X POST .../workers/assets/upload?base64true \ -H Authorization: Bearer $UPLOAD_JWT \ -F 08f1dfda4574284ab3c21666d1ee8c7d4BASE64_CONTENT # 返回completion jwt注意通常需要把文件上传到返回的所有 bucket URL一般为 2 个用于冗余使用相同 JWT 与哈希。8. Outbound Worker Not Intercepting Calls——出站 Worker 未拦截调用根因Outbound Worker 不会拦截 Durable Object 或 mTLS 绑定的 fetch。解法据此规划出口控制策略——并非所有 fetch 调用都会被拦截只有常规的fetch()才会经过 Outbound Worker。9. TCP Socket Connection Failed——TCP Socket 连接失败根因启用 Outbound Worker 后会阻断 TCP 套接字的connect()API。解法Outbound Worker 只拦截fetch()调用配置了 outbound 后 TCP 套接字连接不可用。若业务确需 TCP则移除 outbound 配置或改用代理模式。10. API Rate Limit Exceeded——API 速率限制超限根因超出 Cloudflare API 速率限制每账户每 5 分钟 1200 次请求、每 IP 每秒 200 次请求。解法实现指数退避重试async function deployWithBackoff(deploy: () Promisevoid, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await deploy(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }该函数在收到 429 时依次等待 1s、2s、4s 后重试重试耗尽后抛出原始错误。大规模部署如 AI 生成代码平台批量上线 Worker时建议配合本地排队限速避免集中突发触发 429。11. Gradual Deployment Not Supported——不支持渐进式部署根因对分发命名空间中的用户 Worker 尝试使用渐进式灰度部署。解法WfP 不支持用户 Worker 的渐进式部署只能全量一次性部署。如需灰度应在分发 Worker 内部实现分阶段放量逻辑——例如基于特性开关feature flags或按比例路由percentage-based routing把请求分流到新旧版本 Worker。12. Asset Session Expired——资源会话过期根因上传 JWT 过期有效期 1 小时或完成令牌过期上传后 1 小时。解法在会话创建后 1 小时内完成资源上传并在上传完成后 1 小时内部署 Worker。对于超大上传应分批处理文件或提高上传并行度避免因耗时过长导致会话失效。三、平台限制Platform Limits下表是 WfP 区别于普通 Workers 的关键限制边界直接影响多租户架构设计限制项数值说明每个命名空间的 Worker 数无限制区别于普通 Workers 每账户 500 个脚本的限制每账户命名空间数无限制最佳实践1 个生产 1 个预发staging每个 Worker 最大标签数8用于过滤与组织Worker 模式默认 Untrusted除非启用信任模式否则无request.cf访问权缓存隔离每 Worker 独立untrusted信任模式下共享缓存需使用键前缀隔离Durable Object 命名空间无限制WfP 无每账户 DO 限制渐进式部署不支持仅全量一次性部署caches.default禁用untrusted应使用带自定义键的 Cache API关于信任模式的重要细节见 configuration.mduntrusted 模式下 Worker 无request.cf访问权、缓存按 Worker 隔离、caches.default被禁用启用 trusted 模式trusted_workers: true后命名空间内 Worker 共享缓存必须用键前缀如customer-${id}:${key}隔离、request.cf可访问且需要重新部署既有 Worker 才能生效。信任模式适合内部平台、A/B 测试平台或需要地理定位数据的场景运行不可信客户代码时务必保持默认的 untrusted 模式。四、静态资源上传限制Asset Upload Limits限制项数值说明上传会话 JWT 有效期1 小时必须在此时间内完成上传完成令牌有效期1 小时上传后必须在此时间内完成部署资源哈希格式SHA-256 前 16 字节32 个十六进制字符Base64 编码必须二进制文件必须编码补充两点隔离细节见 api.md默认情况下命名空间内资源是共享的如需客户级隔离可对哈希加盐sha256(customerId fileContents).slice(0, 32)即把客户标识拼入文件内容后再取哈希前 32 字符保证不同客户的同名文件生成不同哈希从而天然隔离。五、API 速率限制API Rate Limits限制类型数值范围Client API每 5 分钟 1200 次请求每账户Client API每秒 200 次请求每 IP 地址GraphQL因查询成本而异按查询复杂度若需通过 GraphQL 查询 WfP 调用量见 patterns.md 的观测示例可参考如下查询结构query { viewer { accounts(filter: {accountTag: $accountId}) { workersInvocationsAdaptive(filter: {dispatchNamespaceName: production}) { sum { requests errors cpuTime } } } } }六、运行限制Operational Limits操作限制说明CPU 时间自定义限制最高为 Workers 套餐上限可在分发 Worker 中按调用设置子请求自定义限制最高为 Workers 套餐上限可在分发 Worker 中按调用设置Outbound Worker 子请求DO/mTLS 不拦截仅拦截常规fetch()调用启用 outbound 时的 TCP 套接字禁用connect()API 不可用自定义限额的完整写法TypeScript 类型见 api.mdinterface DynamicDispatchLimits { cpuMs?: number; // 最大 CPU 毫秒数 subRequests?: number; // 最大 fetch() 调用次数 } const userWorker env.DISPATCHER.get(customer-123, {}, { limits: { cpuMs: 50, subRequests: 20 }, outbound: { customerId: 123, url: request.url } });限额并非建议值而是强制的资源上限一旦触发即抛出 CPU 时间超限异常因此必须配合第二部分CPU time limit exceeded的处理方式记录 Analytics Engine 返回 429一起使用。七、把排障手段组合成生产级方案单独解决单个错误还不够结合 patterns.md 与 configuration.md可将上述修复手段组合为生产级排障与治理闭环观测先行在分发 Worker 上启用 Logpush可按 Outcome 或 Script Name 过滤配合 Tail Workers 实时查看console.log()、异常与诊断信息违规数据统一写入 Analytics Engine例如env.ANALYTICS.writeDataPoint({ indexes: [customerName], blobs: [cpu_limit_exceeded] })为后续调整套餐限额提供依据。按套餐设限在 KV 中存储每个客户的套餐调用get()时按enterprise / pro / free传入不同limits从源头减少 CPU 超限类 429。路由兜底无论子域路由、路径路由还是 KV 路由统一捕获Worker not found返回 404并对缺失 Worker 做友好降级api.md 提供了三类路由的完整示例。更新保绑定所有通过 API 更新 Worker 元数据的操作显式携带keep_bindings防止静默丢失 KV/D1/R2 等关键绑定。部署限速批量上线时用指数退避第二节第 10 条代码应对 429同时利用标签customer-123、production等实现批量过滤与定向清理。八、关联参考文档gotchas.md本文源文档——错误、限制与极限参数速查表README.md——WfP 架构、用例与决策树configuration.md——命名空间、绑定、信任模式、静态资源配置api.md——部署 API、TypeScript SDK、路由与 Outbound Worker 实现patterns.md——多租户、计费、资源隔离与观测模式【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Workers for Platforms 排障手册：常见错误、平台限制与极限参数全解析
Cloudflare Workers for Platforms 排障手册常见错误、平台限制与极限参数全解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文是 Cloudflare Workers for Platforms下称 WfP多租户平台的权威排障参考完整梳理了动态分发命名空间Dispatch Namespace下最容易踩坑的 11 类运行时错误、4 类平台硬性限制平台限制、静态资源上传限制、API 速率限制、运行限制以及对应的修复方案。读完本文你将掌握 Worker not found、CPU 时间超限、绑定丢失、ES Module 部署失败等高频问题的根因定位与可复用的 TypeScript/curl 修复代码并能据此设计出可靠的限流重试、资源隔离与灰度发布方案。一、先理解排障的上下文WfP 的四组件架构所有下文错误与限制都发生在 WfP 特有的四组件架构中先明确各自职责才能精准定位问题出在哪一环Dispatch Namespace分发命名空间容纳无限量客户 Worker 的容器默认以 untrusted不信任模式隔离——无request.cf访问权、无共享缓存。Dynamic Dispatch Worker动态分发 Worker平台入口负责路由请求并强制执行平台逻辑鉴权、限额、校验。User Workers用户 Worker客户代码运行在隔离沙箱中通过 API 部署可选绑定 KV/D1/R2/Durable Objects 等。Outbound Worker出站 Worker可选拦截用户 Worker 的外部fetch()控制出站流量并记录子请求。请求流为Request → Dispatch Worker → env.DISPATCHER.get(customer) → User Worker外部 fetch 经 Outbound Worker→ Response → Dispatch Worker → Client。完整的架构与路由决策树可参考 README.md本节背景正是理解为什么会有这些 Gotchas的基础。二、常见错误逐一排查Common Errors1. Worker not found——请求了不存在的 Worker根因对命名空间中不存在的 Worker 调用了get()从而触发报错。解法捕获该错误并回退为 404 响应同时注意把意外错误重新抛出避免吞掉真实故障try { const userWorker env.DISPATCHER.get(workerName); return userWorker.fetch(request); } catch (e) { if (e.message.startsWith(Worker not found)) { return new Response(Worker not found, { status: 404 }); } throw e; // Re-throw unexpected errors }实践建议在 patterns.md 的路由模式中推荐先将主机名到 Worker 的映射存放在 KV例如键hostname:${hostname}由分发 Worker 查询后再get()这样能在调用前先判断 Worker 是否存在从源头减少 404 抖动。2. CPU time limit exceeded——CPU 时间超限根因用户 Worker 执行超出了为其配置的 CPU 时间限制。解法在分发 Worker 中捕获异常将违规记录到 Analytics Engine 并返回 429 响应同时考虑按客户套餐enterprise/pro/free调整限额try { return await userWorker.fetch(request); } catch (e) { if (e.message.includes(CPU time limit)) { // 记录违规便于计量与告警 env.ANALYTICS.writeDataPoint({ indexes: [workerName], blobs: [cpu_limit_exceeded], }); return new Response(CPU limit exceeded, { status: 429 }); } throw e; }配套的限额设置方式见 configuration.md 与 api.md通过env.DISPATCHER.get(workerName, {}, { limits: { cpuMs, subRequests } })在单次调用级覆盖限额patterns.md 给出了按套餐设限的完整实现例如 free 套餐{ cpuMs: 10, subRequests: 5 }、pro 套餐{ cpuMs: 20, subRequests: 20 }、enterprise 套餐{ cpuMs: 50, subRequests: 50 }。3. Hostname Routing Issues——主机名路由异常根因DNS 代理设置导致路由出现问题。解法改用*/*通配路由。该路由在任何 DNS 代理设置下均生效尤其能保证橙色到橙色orange-to-orange客户站点与你的 Workers 域都走 Cloudflare 代理路由的一致性。补充说明依据 patterns.md 的 O2O 行为表客户未使用 Cloudflare 时*/*与*.domain.com/*均可客户使用代理 CNAME 时必须在边缘调用 Worker只有*/*生效客户使用仅 DNS 的 CNAME 时任意路由均可。官方建议始终使用*/*通配路由以保持一致的 O2O 行为。4. Bindings Lost on Update——更新后绑定丢失根因更新 Worker 时未使用keep_bindings标志导致原有绑定被覆盖清除。解法在 API 请求中使用keep_bindings: true或按类型列出保留项以在更新期间保留既有绑定{ bindings: [{type: r2_bucket, name: STORAGE, bucket_name: new}], keep_bindings: [kv_namespace, d1] // Preserves existing bindings of these types }WfP 支持共 29 类绑定KV、D1、R2、Durable Objects、Analytics Engine、Service、Assets、Queue、Vectorize、Hyperdrive、Workflow、AI、Browser 等完整类型清单见 bindings 文档。5. Tag Filtering Not Working——标签过滤失效根因标签过滤条件中的特殊字符未做 URL 编码。解法对标签做 URL 编码例如tagsproduction%3Ayes并避免使用,与这类特殊字符。配套的标签操作命令见 configuration.md# 设置标签 curl -X PUT .../tags -d [customer-123, pro, production] # 按标签过滤注意 %3A 即 : 的 URL 编码 curl .../scripts?tagsproduction%3Ayes # 按标签批量删除 curl -X DELETE .../scripts?tagscustomer-123%3Ayes常用标签模式customer-123、free|pro|enterprise、production|staging。每个 Worker 最多 8 个标签标签化是批量操作列表、过滤、删除的基础。6. Deploy Failures with ES Modules——ES Module 部署失败根因ES Module 的上传格式不正确。解法使用 multipart 表单上传在 metadata 中指定main_module并将文件类型设为application/javascriptmodulecurl -X PUT \ https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME \ -H Authorization: Bearer $API_TOKEN \ -F metadata{main_module: worker.mjs};typeapplication/json \ -F worker.mjsworker.mjs;typeapplication/javascriptmoduleTypeScript SDK 的等价写法见 api.mdimport Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env.API_TOKEN }); const scriptFile new File([scriptContent], ${scriptName}.mjs, { type: application/javascriptmodule, }); await client.workersForPlatforms.dispatch.namespaces.scripts.update( namespace, scriptName, { account_id: accountId, metadata: { main_module: ${scriptName}.mjs }, files: [scriptFile], } );部署时建议在 metadata 中携带compatibility_date新项目使用当前日期避免因兼容性日期缺失导致运行时不兼容。7. Static Asset Upload Failed——静态资源上传失败根因哈希格式非法、令牌过期或编码不正确。解法需同时满足三条约束哈希必须是 SHA-256 的前 16 字节32 个十六进制字符必须在会话创建后 1 小时内完成上传必须在上传完成后 1 小时内完成 Worker 部署文件内容必须做 Base64 编码。配套的三步上传流程见 api.md# 1. 创建上传会话manifest 中的 hash 为 SHA-256 前 16 字节 curl -X POST .../scripts/$SCRIPT_NAME/assets-upload-session \ -H Authorization: Bearer $API_TOKEN \ -d { manifest: { /index.html: {hash: 08f1dfda4574284ab3c21666d1ee8c7d4, size: 1234} } } # 返回jwt, buckets # 2. 上传文件Base64 编码携带上传 JWT curl -X POST .../workers/assets/upload?base64true \ -H Authorization: Bearer $UPLOAD_JWT \ -F 08f1dfda4574284ab3c21666d1ee8c7d4BASE64_CONTENT # 返回completion jwt注意通常需要把文件上传到返回的所有 bucket URL一般为 2 个用于冗余使用相同 JWT 与哈希。8. Outbound Worker Not Intercepting Calls——出站 Worker 未拦截调用根因Outbound Worker 不会拦截 Durable Object 或 mTLS 绑定的 fetch。解法据此规划出口控制策略——并非所有 fetch 调用都会被拦截只有常规的fetch()才会经过 Outbound Worker。9. TCP Socket Connection Failed——TCP Socket 连接失败根因启用 Outbound Worker 后会阻断 TCP 套接字的connect()API。解法Outbound Worker 只拦截fetch()调用配置了 outbound 后 TCP 套接字连接不可用。若业务确需 TCP则移除 outbound 配置或改用代理模式。10. API Rate Limit Exceeded——API 速率限制超限根因超出 Cloudflare API 速率限制每账户每 5 分钟 1200 次请求、每 IP 每秒 200 次请求。解法实现指数退避重试async function deployWithBackoff(deploy: () Promisevoid, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await deploy(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }该函数在收到 429 时依次等待 1s、2s、4s 后重试重试耗尽后抛出原始错误。大规模部署如 AI 生成代码平台批量上线 Worker时建议配合本地排队限速避免集中突发触发 429。11. Gradual Deployment Not Supported——不支持渐进式部署根因对分发命名空间中的用户 Worker 尝试使用渐进式灰度部署。解法WfP 不支持用户 Worker 的渐进式部署只能全量一次性部署。如需灰度应在分发 Worker 内部实现分阶段放量逻辑——例如基于特性开关feature flags或按比例路由percentage-based routing把请求分流到新旧版本 Worker。12. Asset Session Expired——资源会话过期根因上传 JWT 过期有效期 1 小时或完成令牌过期上传后 1 小时。解法在会话创建后 1 小时内完成资源上传并在上传完成后 1 小时内部署 Worker。对于超大上传应分批处理文件或提高上传并行度避免因耗时过长导致会话失效。三、平台限制Platform Limits下表是 WfP 区别于普通 Workers 的关键限制边界直接影响多租户架构设计限制项数值说明每个命名空间的 Worker 数无限制区别于普通 Workers 每账户 500 个脚本的限制每账户命名空间数无限制最佳实践1 个生产 1 个预发staging每个 Worker 最大标签数8用于过滤与组织Worker 模式默认 Untrusted除非启用信任模式否则无request.cf访问权缓存隔离每 Worker 独立untrusted信任模式下共享缓存需使用键前缀隔离Durable Object 命名空间无限制WfP 无每账户 DO 限制渐进式部署不支持仅全量一次性部署caches.default禁用untrusted应使用带自定义键的 Cache API关于信任模式的重要细节见 configuration.mduntrusted 模式下 Worker 无request.cf访问权、缓存按 Worker 隔离、caches.default被禁用启用 trusted 模式trusted_workers: true后命名空间内 Worker 共享缓存必须用键前缀如customer-${id}:${key}隔离、request.cf可访问且需要重新部署既有 Worker 才能生效。信任模式适合内部平台、A/B 测试平台或需要地理定位数据的场景运行不可信客户代码时务必保持默认的 untrusted 模式。四、静态资源上传限制Asset Upload Limits限制项数值说明上传会话 JWT 有效期1 小时必须在此时间内完成上传完成令牌有效期1 小时上传后必须在此时间内完成部署资源哈希格式SHA-256 前 16 字节32 个十六进制字符Base64 编码必须二进制文件必须编码补充两点隔离细节见 api.md默认情况下命名空间内资源是共享的如需客户级隔离可对哈希加盐sha256(customerId fileContents).slice(0, 32)即把客户标识拼入文件内容后再取哈希前 32 字符保证不同客户的同名文件生成不同哈希从而天然隔离。五、API 速率限制API Rate Limits限制类型数值范围Client API每 5 分钟 1200 次请求每账户Client API每秒 200 次请求每 IP 地址GraphQL因查询成本而异按查询复杂度若需通过 GraphQL 查询 WfP 调用量见 patterns.md 的观测示例可参考如下查询结构query { viewer { accounts(filter: {accountTag: $accountId}) { workersInvocationsAdaptive(filter: {dispatchNamespaceName: production}) { sum { requests errors cpuTime } } } } }六、运行限制Operational Limits操作限制说明CPU 时间自定义限制最高为 Workers 套餐上限可在分发 Worker 中按调用设置子请求自定义限制最高为 Workers 套餐上限可在分发 Worker 中按调用设置Outbound Worker 子请求DO/mTLS 不拦截仅拦截常规fetch()调用启用 outbound 时的 TCP 套接字禁用connect()API 不可用自定义限额的完整写法TypeScript 类型见 api.mdinterface DynamicDispatchLimits { cpuMs?: number; // 最大 CPU 毫秒数 subRequests?: number; // 最大 fetch() 调用次数 } const userWorker env.DISPATCHER.get(customer-123, {}, { limits: { cpuMs: 50, subRequests: 20 }, outbound: { customerId: 123, url: request.url } });限额并非建议值而是强制的资源上限一旦触发即抛出 CPU 时间超限异常因此必须配合第二部分CPU time limit exceeded的处理方式记录 Analytics Engine 返回 429一起使用。七、把排障手段组合成生产级方案单独解决单个错误还不够结合 patterns.md 与 configuration.md可将上述修复手段组合为生产级排障与治理闭环观测先行在分发 Worker 上启用 Logpush可按 Outcome 或 Script Name 过滤配合 Tail Workers 实时查看console.log()、异常与诊断信息违规数据统一写入 Analytics Engine例如env.ANALYTICS.writeDataPoint({ indexes: [customerName], blobs: [cpu_limit_exceeded] })为后续调整套餐限额提供依据。按套餐设限在 KV 中存储每个客户的套餐调用get()时按enterprise / pro / free传入不同limits从源头减少 CPU 超限类 429。路由兜底无论子域路由、路径路由还是 KV 路由统一捕获Worker not found返回 404并对缺失 Worker 做友好降级api.md 提供了三类路由的完整示例。更新保绑定所有通过 API 更新 Worker 元数据的操作显式携带keep_bindings防止静默丢失 KV/D1/R2 等关键绑定。部署限速批量上线时用指数退避第二节第 10 条代码应对 429同时利用标签customer-123、production等实现批量过滤与定向清理。八、关联参考文档gotchas.md本文源文档——错误、限制与极限参数速查表README.md——WfP 架构、用例与决策树configuration.md——命名空间、绑定、信任模式、静态资源配置api.md——部署 API、TypeScript SDK、路由与 Outbound Worker 实现patterns.md——多租户、计费、资源隔离与观测模式【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考