Cloudflare Wrangler 配置完全指南wrangler.jsonc 从入门到进阶【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 cloudflare-deploy 技能中 Wrangler 配置参考 为核心系统讲解 Workers 部署的核心配置文件wrangler.jsonc推荐格式包括配置格式与字段继承规则、多环境管理、路由、全部类型的 BindingsKV / D1 / R2 / Durable Objects / Service Bindings / Queues / Vectorize / Hyperdrive / Workers AI / Workflows / Secrets Store 等、静态资源托管、Smart Placement、自动预置Auto-Provisioning以及 Cron、Observability、mTLS、Logpush 等进阶能力。读者学完后能够独立编写一套可部署、可多环境复用的 Wrangler 配置文件并理解配置项背后的运行时行为。为什么使用 wrangler.jsoncwrangler.jsonc是 WranglerCloudflare Workers 官方 CLI自 v3.91.0 起推荐的配置文件格式。相比旧的wrangler.tomlJSONCJSON with Comments最大的优势是支持 schema 校验借助编辑器插件读取$schema字段即可在编写配置时获得字段名、类型与取值范围的即时提示与错误检测显著降低手写配置的出错率。安装 Wrangler 并初始化项目后即可开始编写配置详见 Wrangler READMEnpm install wrangler --save-dev npx wrangler init my-worker # 创建新项目骨架提示配置写完后可用npx wrangler check校验配置合法性参考 gotchas.md。配置格式与最小示例wrangler.jsonc的核心字段包括项目名name、入口文件main、兼容日期compatibility_date、环境变量vars以及各类资源绑定。一个最小可用配置如下{ $schema: ./node_modules/wrangler/config-schema.json, name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // 建议填写当前日期 vars: { API_KEY: dev-key }, kv_namespaces: [{ binding: MY_KV, id: abc123 }] }各字段说明字段作用备注$schema指向 Wrangler 自带的 JSON Schema 文件启用编辑器智能校验nameWorker 名称也用于生成*.workers.dev子域名mainWorker 入口源码路径通常为src/index.tscompatibility_date声明使用的运行时兼容日期建议始终显式设置缺失会导致运行时行为不可预期详见下文「常见陷阱」vars普通环境变量明文适合非敏感配置敏感信息应使用wrangler secretkv_namespacesKV 命名空间绑定通过binding在代码中访问compatibility_date 为什么重要compatibility_date决定了 Workers 运行时为你启用哪些行为变更是配置中最容易忽略却影响最大的字段之一。在 gotchas.md 的「Unexpected runtime changes」一节中明确将「Missing compatibility_date」列为运行时行为突变的根因。实践上新项目填写创建当天的日期升级依赖时按官方迁移指引逐步推进日期。字段继承规则Field Inheritance多环境配置env字段下Wrangler 对顶层字段采取「可继承 / 不可继承」两种策略可继承Inheritablename、main、compatibility_date、routes、triggers。子环境若不显式声明则自动继承顶层的值也可按需覆盖。不可继承Non-inheritablevars、以及各类绑定KV、D1、R2 等。每个环境必须重新定义否则该环境运行时会提示绑定缺失。这一点与 gotchas.md 中「Environment not inheriting config」的常见错误直接对应很多开发者误以为绑定会自动继承结果在 staging / production 环境遇到「Binding Not Available」。多环境配置Environments通过顶层env字段定义命名环境配合wrangler deploy --env name部署{ name: my-worker, vars: { ENV: dev }, env: { production: { name: my-worker-prod, vars: { ENV: prod }, route: { pattern: example.com/*, zone_name: example.com } } } }部署与验证命令wrangler deploy --env production # 部署到 production 环境 wrangler tail --env production # 查看 production 实时日志 wrangler versions list # 列出已部署版本 wrangler rollback [id] # 回滚到指定版本命令详见 README.md 的 Essential Commands 与 Monitoring 小节。环境数量没有硬性上限参考 gotchas.md 的 Limits 表常见做法是划分dev/staging/production并将敏感环境专属绑定如生产 D1 的database_id只写在对应env块内。路由配置RoutingWrangler 支持三种路由方式可按需组合// 1. 自定义域名推荐自动签发证书 { routes: [{ pattern: api.example.com, custom_domain: true }] } // 2. 基于 Zone 的路由挂载到已有 Cloudflare 域名 { routes: [{ pattern: api.example.com/*, zone_name: example.com }] } // 3. workers.dev 子域名零配置开发用 { workers_dev: true }custom_domain: true将 Worker 直接绑定为独立自定义域名Cloudflare 自动处理证书生产推荐zone_name指定路由所属的 DNS Zone适合在已有站点下挂路径或子域workers_dev开启后可通过name.workers.dev访问适合快速验证与演示。Bindings连接 Cloudflare 各类资源Bindings 是 Worker 访问平台资源的统一入口。一个 Worker 的绑定总数上限为64 个全部类型合计见 gotchas.md Limits 表。以下配置片段均摘自 configuration.md 的 Bindings 一节。变量与 KV// 普通变量代码中通过 env.API_URL 读取 { vars: { API_URL: https://api.example.com } } // KV键值存储缓存、会话、配置 { kv_namespaces: [{ binding: CACHE, id: abc123 }] }KV 命名空间需先用 CLI 创建wrangler kv namespace create NAME将返回的 ID 填入配置--preview可创建用于本地预览的命名空间见 patterns.md。D1 与 R2// D1SQLite 关系型数据库 { d1_databases: [{ binding: DB, database_id: abc-123 }] } // R2S3 兼容对象存储 { r2_buckets: [{ binding: ASSETS, bucket_name: my-assets }] }对应资源创建命令README.mdwrangler d1 create my-db wrangler d1 migrations create my-db initial_schema wrangler d1 migrations apply my-db --local wrangler d1 migrations apply my-db --remote wrangler r2 bucket create my-assetsDurable Objects含迁移{ durable_objects: { bindings: [{ name: COUNTER, class_name: Counter, script_name: my-worker // 外部 DO 必填 }] } } { migrations: [{ tag: v1, new_sqlite_classes: [Counter] }] }注意script_name用于引用其他 Worker中定义的 Durable Object对于同 Worker 内的本地 DOscript_name可省略见 gotchas.md「Durable Object binding not working」。新引入的 DO 类必须通过migrations.new_sqlite_classes声明否则部署会失败。Service BindingsWorker 间调用{ services: [{ binding: AUTH, service: auth-worker }] }代码中通过env.AUTH.fetch()调用另一个 Worker是拆分微服务式 Worker 的基础能力。测试阶段可用 Wrangler 的 Multi-Worker Registry 注入本地 Worker 实例进行联调见 api.md。Queues消息队列{ queues: { producers: [{ binding: TASKS, queue: task-queue }], consumers: [{ queue: task-queue, max_batch_size: 10 }] } }producers用于向队列投递消息consumers声明消费队列及其批量大小适合异步任务处理。Vectorize 与 Hyperdrive// Vectorize向量数据库AI 语义检索 / RAG { vectorize: [{ binding: VECTORS, index_name: embeddings }] } // Hyperdrive加速访问外部 Postgres/MySQL { hyperdrive: [{ binding: HYPERDRIVE, id: hyper-id }] } { compatibility_flags: [nodejs_compat_v2] } // pg/postgres 客户端必需Hyperdrive 用于缓存并加速对已有关系数据库的连接若在 Worker 中使用 Node.js 生态的pg驱动访问 Postgres必须同时开启nodejs_compat_v2兼容标志见 gotchas.md「Node.js compatibility error」。Workers AI、Workflows 与 Secrets Store// Workers AI边缘运行 AI 推理LLM / 嵌入 / 图像 { ai: { binding: AI } } // Workflows长时多步骤任务编排 { workflows: [{ binding: WORKFLOW, name: my-workflow, class_name: MyWorkflow }] } // Secrets Store集中式密钥管理可跨 Worker 复用 { secrets_store: [{ binding: SECRETS, id: store-id }] }Secrets Store 与传统wrangler secret的区别在于集中管理、可被多个 Worker 复用传统密钥通过wrangler secret put NAME注入且仅对已部署 Worker 生效本地开发需改用.dev.vars文件详见 patterns.md 与 gotchas.md。ConstellationAI 推理{ constellation: [{ binding: MODEL, project_id: proj-id }] }绑定命名要点binding是代码中的变量名如env.MY_KVid/database_id/bucket_name等是资源 ID二者容易混淆见 gotchas.md「Binding ID vs name mismatch」预览环境如需独立资源可为 KV、D1 等配置preview_id/preview_database_id本地开发时部分绑定需要wrangler dev --remote才能访问真实远端资源。Workers Assets静态文件托管Workers Assets 取代了旧的site配置是当前在 Worker 中托管静态文件的推荐方式{ assets: { directory: ./public, binding: ASSETS, html_handling: auto-trailing-slash, // 或 none、force-trailing-slash not_found_handling: single-page-application // 或 404-page、none } }directory静态资源目录构建产物html_handling控制 HTML 路径与斜杠的处理策略not_found_handling控制 404 时的行为single-page-application会将 404 回退到index.html适合 SPA。在 Worker 代码中优先尝试静态资源未命中再走自定义逻辑export default { async fetch(request, env) { // 先尝试返回静态资源 const asset await env.ASSETS.fetch(request); if (asset.status ! 404) return asset; // 非静态资源走自定义 API 逻辑 return new Response(API response); } }限制单次部署静态资源总大小上限 25 MB、文件数上限 20,000 个见 gotchas.md。若遇到 404优先检查directory是否指向正确的构建输出目录、html_handling与not_found_handling是否符合站点形态。Placement控制 Worker 运行地域{ placement: { mode: smart // 或 off } }smart将 Worker 调度到数据源附近运行降低访问 D1、Durable Objects 的延迟off默认分布式运行在全球边缘任意位置执行。重要前提Smart Placement 只在 Worker 访问 D1 或 Durable Objects 时才有收益对 KV、R2 或外部 API 的延迟没有帮助——配置后效果不明显往往是因为用错了场景见 gotchas.md「Placement not reducing latency」。Auto-ProvisioningBeta免填资源 ID在 Beta 阶段配置绑定资源时可以省略资源 ID由 Wrangler 在首次deploy时自动创建资源并把生成的 ID回写进配置文件{ kv_namespaces: [{ binding: MY_KV }] } // 不写 id自动预置部署后配置文件中会自动补上id字段。实践要点gotchas.md「Auto-provisioned resources not appearing」首次部署后配置已被更新请提交更新后的配置文件后续部署会复用已有资源不会重复创建若发现资源「没有出现」通常是配置更新后未重新加载/提交所致。进阶配置Advanced以下配置覆盖调度、可观测性与安全相关能力// Cron Triggers定时触发 { triggers: { crons: [0 0 * * *] } } // Observability分布式追踪head_sampling_rate 为头部采样率 { observability: { enabled: true, head_sampling_rate: 0.1 } } // Runtime LimitsCPU 时间上限毫秒 { limits: { cpu_ms: 100 } } // Browser Rendering无头浏览器 { browser: { binding: BROWSER } } // mTLS Certificates双向 TLS 客户端证书 { mtls_certificates: [{ binding: CERT, certificate_id: cert-uuid }] } // Logpush将日志流式投递到 R2/S3 { logpush: true } // Tail Consumers由另一个 Worker 消费日志如聚合分析 { tail_consumers: [{ service: log-worker }] } // Unsafe bindings声明任意类型的绑定非标准字段时使用 { unsafe: { bindings: [{ name: MY_BINDING, type: plain_text, text: value }] } }其中 Logpush 与 Tail Consumers 是生产环境日志管线的两种方向前者面向归档分析R2/S3后者面向实时处理另一个 Worker二者可以互补使用。结合源码与测试配置如何驱动开发闭环配置的价值不止于部署它同时驱动本地开发、类型生成与集成测试三个环节本地开发wrangler dev直接读取wrangler.jsonc模拟运行时wrangler dev --remote则按配置访问真实远端资源见 patterns.md类型生成运行wrangler types基于配置生成worker-configuration.d.ts让env.MY_KV等绑定在 TypeScript 中获得完整类型提示export default { async fetch(request: Request, env: Env): PromiseResponse { return Response.json({ value: await env.MY_KV.get(key) }); } } satisfies ExportedHandlerEnv;官方建议在每次修改配置后重新执行wrangler types见 api.md Best Practices集成测试Wrangler 的编程 APIstartWorker可直接传入config: wrangler.jsonc启动带真实本地绑定的 Worker 实例配合environment、remote等选项覆盖不同环境api.mdimport { startWorker } from wrangler; const worker await startWorker({ config: wrangler.jsonc, environment: development, remote: minimal // 快速测试 真实远端绑定 }); // worker.fetch(...) 发起请求断言 await worker.dispose(); // 必须清理防止资源泄漏配置排错速查常见陷阱结合 gotchas.md整理配置相关的高频问题与对策症状根因对策绑定名与 ID 混淆分不清binding代码名与id资源 ID严格按字段语义填写预览环境用preview_id环境不继承配置不可继承字段bindings、vars未在环境内重定义每个环境显式定义 vars 与绑定运行时行为突变缺失compatibility_date始终显式设置兼容日期DO 绑定不工作外部 DO 缺少script_name外部 DO 必须填写script_name本地无密钥wrangler secret仅对线上生效本地用.dev.vars使用pg报兼容错误缺少nodejs_compat_v2开启对应 compatibility flagAssets 404目录路径或 html 处理策略不对检查assets.directorySPA 用single-page-application配置校验失败字段书写错误用wrangler check校验并借助$schema提示延伸阅读Wrangler 总览与常用命令安装、init/dev/deploy、KV/D1/R2 资源管理、secret 与 tailWrangler 编程 APIstartWorker、getPlatformProxy、事件系统与动态重配置Wrangler 开发模式New Worker、本地开发、D1 迁移、Vitest 测试与多 Worker 联调Wrangler 常见问题错误清单、限额表与排错命令Wrangler 认证配置wrangler login与 CI/CD 的 API Tokencloudflare-deploy 技能入口按场景选择产品并加载对应参考资料【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Wrangler 配置完全指南：wrangler.jsonc 从入门到进阶
Cloudflare Wrangler 配置完全指南wrangler.jsonc 从入门到进阶【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 cloudflare-deploy 技能中 Wrangler 配置参考 为核心系统讲解 Workers 部署的核心配置文件wrangler.jsonc推荐格式包括配置格式与字段继承规则、多环境管理、路由、全部类型的 BindingsKV / D1 / R2 / Durable Objects / Service Bindings / Queues / Vectorize / Hyperdrive / Workers AI / Workflows / Secrets Store 等、静态资源托管、Smart Placement、自动预置Auto-Provisioning以及 Cron、Observability、mTLS、Logpush 等进阶能力。读者学完后能够独立编写一套可部署、可多环境复用的 Wrangler 配置文件并理解配置项背后的运行时行为。为什么使用 wrangler.jsoncwrangler.jsonc是 WranglerCloudflare Workers 官方 CLI自 v3.91.0 起推荐的配置文件格式。相比旧的wrangler.tomlJSONCJSON with Comments最大的优势是支持 schema 校验借助编辑器插件读取$schema字段即可在编写配置时获得字段名、类型与取值范围的即时提示与错误检测显著降低手写配置的出错率。安装 Wrangler 并初始化项目后即可开始编写配置详见 Wrangler READMEnpm install wrangler --save-dev npx wrangler init my-worker # 创建新项目骨架提示配置写完后可用npx wrangler check校验配置合法性参考 gotchas.md。配置格式与最小示例wrangler.jsonc的核心字段包括项目名name、入口文件main、兼容日期compatibility_date、环境变量vars以及各类资源绑定。一个最小可用配置如下{ $schema: ./node_modules/wrangler/config-schema.json, name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // 建议填写当前日期 vars: { API_KEY: dev-key }, kv_namespaces: [{ binding: MY_KV, id: abc123 }] }各字段说明字段作用备注$schema指向 Wrangler 自带的 JSON Schema 文件启用编辑器智能校验nameWorker 名称也用于生成*.workers.dev子域名mainWorker 入口源码路径通常为src/index.tscompatibility_date声明使用的运行时兼容日期建议始终显式设置缺失会导致运行时行为不可预期详见下文「常见陷阱」vars普通环境变量明文适合非敏感配置敏感信息应使用wrangler secretkv_namespacesKV 命名空间绑定通过binding在代码中访问compatibility_date 为什么重要compatibility_date决定了 Workers 运行时为你启用哪些行为变更是配置中最容易忽略却影响最大的字段之一。在 gotchas.md 的「Unexpected runtime changes」一节中明确将「Missing compatibility_date」列为运行时行为突变的根因。实践上新项目填写创建当天的日期升级依赖时按官方迁移指引逐步推进日期。字段继承规则Field Inheritance多环境配置env字段下Wrangler 对顶层字段采取「可继承 / 不可继承」两种策略可继承Inheritablename、main、compatibility_date、routes、triggers。子环境若不显式声明则自动继承顶层的值也可按需覆盖。不可继承Non-inheritablevars、以及各类绑定KV、D1、R2 等。每个环境必须重新定义否则该环境运行时会提示绑定缺失。这一点与 gotchas.md 中「Environment not inheriting config」的常见错误直接对应很多开发者误以为绑定会自动继承结果在 staging / production 环境遇到「Binding Not Available」。多环境配置Environments通过顶层env字段定义命名环境配合wrangler deploy --env name部署{ name: my-worker, vars: { ENV: dev }, env: { production: { name: my-worker-prod, vars: { ENV: prod }, route: { pattern: example.com/*, zone_name: example.com } } } }部署与验证命令wrangler deploy --env production # 部署到 production 环境 wrangler tail --env production # 查看 production 实时日志 wrangler versions list # 列出已部署版本 wrangler rollback [id] # 回滚到指定版本命令详见 README.md 的 Essential Commands 与 Monitoring 小节。环境数量没有硬性上限参考 gotchas.md 的 Limits 表常见做法是划分dev/staging/production并将敏感环境专属绑定如生产 D1 的database_id只写在对应env块内。路由配置RoutingWrangler 支持三种路由方式可按需组合// 1. 自定义域名推荐自动签发证书 { routes: [{ pattern: api.example.com, custom_domain: true }] } // 2. 基于 Zone 的路由挂载到已有 Cloudflare 域名 { routes: [{ pattern: api.example.com/*, zone_name: example.com }] } // 3. workers.dev 子域名零配置开发用 { workers_dev: true }custom_domain: true将 Worker 直接绑定为独立自定义域名Cloudflare 自动处理证书生产推荐zone_name指定路由所属的 DNS Zone适合在已有站点下挂路径或子域workers_dev开启后可通过name.workers.dev访问适合快速验证与演示。Bindings连接 Cloudflare 各类资源Bindings 是 Worker 访问平台资源的统一入口。一个 Worker 的绑定总数上限为64 个全部类型合计见 gotchas.md Limits 表。以下配置片段均摘自 configuration.md 的 Bindings 一节。变量与 KV// 普通变量代码中通过 env.API_URL 读取 { vars: { API_URL: https://api.example.com } } // KV键值存储缓存、会话、配置 { kv_namespaces: [{ binding: CACHE, id: abc123 }] }KV 命名空间需先用 CLI 创建wrangler kv namespace create NAME将返回的 ID 填入配置--preview可创建用于本地预览的命名空间见 patterns.md。D1 与 R2// D1SQLite 关系型数据库 { d1_databases: [{ binding: DB, database_id: abc-123 }] } // R2S3 兼容对象存储 { r2_buckets: [{ binding: ASSETS, bucket_name: my-assets }] }对应资源创建命令README.mdwrangler d1 create my-db wrangler d1 migrations create my-db initial_schema wrangler d1 migrations apply my-db --local wrangler d1 migrations apply my-db --remote wrangler r2 bucket create my-assetsDurable Objects含迁移{ durable_objects: { bindings: [{ name: COUNTER, class_name: Counter, script_name: my-worker // 外部 DO 必填 }] } } { migrations: [{ tag: v1, new_sqlite_classes: [Counter] }] }注意script_name用于引用其他 Worker中定义的 Durable Object对于同 Worker 内的本地 DOscript_name可省略见 gotchas.md「Durable Object binding not working」。新引入的 DO 类必须通过migrations.new_sqlite_classes声明否则部署会失败。Service BindingsWorker 间调用{ services: [{ binding: AUTH, service: auth-worker }] }代码中通过env.AUTH.fetch()调用另一个 Worker是拆分微服务式 Worker 的基础能力。测试阶段可用 Wrangler 的 Multi-Worker Registry 注入本地 Worker 实例进行联调见 api.md。Queues消息队列{ queues: { producers: [{ binding: TASKS, queue: task-queue }], consumers: [{ queue: task-queue, max_batch_size: 10 }] } }producers用于向队列投递消息consumers声明消费队列及其批量大小适合异步任务处理。Vectorize 与 Hyperdrive// Vectorize向量数据库AI 语义检索 / RAG { vectorize: [{ binding: VECTORS, index_name: embeddings }] } // Hyperdrive加速访问外部 Postgres/MySQL { hyperdrive: [{ binding: HYPERDRIVE, id: hyper-id }] } { compatibility_flags: [nodejs_compat_v2] } // pg/postgres 客户端必需Hyperdrive 用于缓存并加速对已有关系数据库的连接若在 Worker 中使用 Node.js 生态的pg驱动访问 Postgres必须同时开启nodejs_compat_v2兼容标志见 gotchas.md「Node.js compatibility error」。Workers AI、Workflows 与 Secrets Store// Workers AI边缘运行 AI 推理LLM / 嵌入 / 图像 { ai: { binding: AI } } // Workflows长时多步骤任务编排 { workflows: [{ binding: WORKFLOW, name: my-workflow, class_name: MyWorkflow }] } // Secrets Store集中式密钥管理可跨 Worker 复用 { secrets_store: [{ binding: SECRETS, id: store-id }] }Secrets Store 与传统wrangler secret的区别在于集中管理、可被多个 Worker 复用传统密钥通过wrangler secret put NAME注入且仅对已部署 Worker 生效本地开发需改用.dev.vars文件详见 patterns.md 与 gotchas.md。ConstellationAI 推理{ constellation: [{ binding: MODEL, project_id: proj-id }] }绑定命名要点binding是代码中的变量名如env.MY_KVid/database_id/bucket_name等是资源 ID二者容易混淆见 gotchas.md「Binding ID vs name mismatch」预览环境如需独立资源可为 KV、D1 等配置preview_id/preview_database_id本地开发时部分绑定需要wrangler dev --remote才能访问真实远端资源。Workers Assets静态文件托管Workers Assets 取代了旧的site配置是当前在 Worker 中托管静态文件的推荐方式{ assets: { directory: ./public, binding: ASSETS, html_handling: auto-trailing-slash, // 或 none、force-trailing-slash not_found_handling: single-page-application // 或 404-page、none } }directory静态资源目录构建产物html_handling控制 HTML 路径与斜杠的处理策略not_found_handling控制 404 时的行为single-page-application会将 404 回退到index.html适合 SPA。在 Worker 代码中优先尝试静态资源未命中再走自定义逻辑export default { async fetch(request, env) { // 先尝试返回静态资源 const asset await env.ASSETS.fetch(request); if (asset.status ! 404) return asset; // 非静态资源走自定义 API 逻辑 return new Response(API response); } }限制单次部署静态资源总大小上限 25 MB、文件数上限 20,000 个见 gotchas.md。若遇到 404优先检查directory是否指向正确的构建输出目录、html_handling与not_found_handling是否符合站点形态。Placement控制 Worker 运行地域{ placement: { mode: smart // 或 off } }smart将 Worker 调度到数据源附近运行降低访问 D1、Durable Objects 的延迟off默认分布式运行在全球边缘任意位置执行。重要前提Smart Placement 只在 Worker 访问 D1 或 Durable Objects 时才有收益对 KV、R2 或外部 API 的延迟没有帮助——配置后效果不明显往往是因为用错了场景见 gotchas.md「Placement not reducing latency」。Auto-ProvisioningBeta免填资源 ID在 Beta 阶段配置绑定资源时可以省略资源 ID由 Wrangler 在首次deploy时自动创建资源并把生成的 ID回写进配置文件{ kv_namespaces: [{ binding: MY_KV }] } // 不写 id自动预置部署后配置文件中会自动补上id字段。实践要点gotchas.md「Auto-provisioned resources not appearing」首次部署后配置已被更新请提交更新后的配置文件后续部署会复用已有资源不会重复创建若发现资源「没有出现」通常是配置更新后未重新加载/提交所致。进阶配置Advanced以下配置覆盖调度、可观测性与安全相关能力// Cron Triggers定时触发 { triggers: { crons: [0 0 * * *] } } // Observability分布式追踪head_sampling_rate 为头部采样率 { observability: { enabled: true, head_sampling_rate: 0.1 } } // Runtime LimitsCPU 时间上限毫秒 { limits: { cpu_ms: 100 } } // Browser Rendering无头浏览器 { browser: { binding: BROWSER } } // mTLS Certificates双向 TLS 客户端证书 { mtls_certificates: [{ binding: CERT, certificate_id: cert-uuid }] } // Logpush将日志流式投递到 R2/S3 { logpush: true } // Tail Consumers由另一个 Worker 消费日志如聚合分析 { tail_consumers: [{ service: log-worker }] } // Unsafe bindings声明任意类型的绑定非标准字段时使用 { unsafe: { bindings: [{ name: MY_BINDING, type: plain_text, text: value }] } }其中 Logpush 与 Tail Consumers 是生产环境日志管线的两种方向前者面向归档分析R2/S3后者面向实时处理另一个 Worker二者可以互补使用。结合源码与测试配置如何驱动开发闭环配置的价值不止于部署它同时驱动本地开发、类型生成与集成测试三个环节本地开发wrangler dev直接读取wrangler.jsonc模拟运行时wrangler dev --remote则按配置访问真实远端资源见 patterns.md类型生成运行wrangler types基于配置生成worker-configuration.d.ts让env.MY_KV等绑定在 TypeScript 中获得完整类型提示export default { async fetch(request: Request, env: Env): PromiseResponse { return Response.json({ value: await env.MY_KV.get(key) }); } } satisfies ExportedHandlerEnv;官方建议在每次修改配置后重新执行wrangler types见 api.md Best Practices集成测试Wrangler 的编程 APIstartWorker可直接传入config: wrangler.jsonc启动带真实本地绑定的 Worker 实例配合environment、remote等选项覆盖不同环境api.mdimport { startWorker } from wrangler; const worker await startWorker({ config: wrangler.jsonc, environment: development, remote: minimal // 快速测试 真实远端绑定 }); // worker.fetch(...) 发起请求断言 await worker.dispose(); // 必须清理防止资源泄漏配置排错速查常见陷阱结合 gotchas.md整理配置相关的高频问题与对策症状根因对策绑定名与 ID 混淆分不清binding代码名与id资源 ID严格按字段语义填写预览环境用preview_id环境不继承配置不可继承字段bindings、vars未在环境内重定义每个环境显式定义 vars 与绑定运行时行为突变缺失compatibility_date始终显式设置兼容日期DO 绑定不工作外部 DO 缺少script_name外部 DO 必须填写script_name本地无密钥wrangler secret仅对线上生效本地用.dev.vars使用pg报兼容错误缺少nodejs_compat_v2开启对应 compatibility flagAssets 404目录路径或 html 处理策略不对检查assets.directorySPA 用single-page-application配置校验失败字段书写错误用wrangler check校验并借助$schema提示延伸阅读Wrangler 总览与常用命令安装、init/dev/deploy、KV/D1/R2 资源管理、secret 与 tailWrangler 编程 APIstartWorker、getPlatformProxy、事件系统与动态重配置Wrangler 开发模式New Worker、本地开发、D1 迁移、Vitest 测试与多 Worker 联调Wrangler 常见问题错误清单、限额表与排错命令Wrangler 认证配置wrangler login与 CI/CD 的 API Tokencloudflare-deploy 技能入口按场景选择产品并加载对应参考资料【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考