Cloudflare Workers 完整配置指南wrangler.jsonc 绑定、环境与 TypeScript 实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文以 Cloudflare Workers 的配置体系为主线系统讲解基于wrangler.jsonc的声明式配置方式从字段继承规则、各类资源绑定KV / R2 / D1 / Durable Objects / Queues 等、多环境拆分到自动类型生成与nodejs_compat_v2等高级选项最后给出生产级部署命令序列。读完本文你将能独立为 Worker 编写一份可校验、可多环境复用、类型安全的wrangler.jsonc并正确配套 Secrets、Cron 触发器与 TypeScript 类型体系。wrangler.jsonc推荐的配置载体Wrangler 支持多种配置文件名官方推荐使用wrangler.jsoncv3.91.0它最大的优势是开箱即用的 JSON Schema 校验配置文件中显式声明$schema指向本地安装的 Wrangler 包内 schema 文件后编辑器即可获得字段提示与错误高亮杜绝手写配置时的低级错误。仓库参考文档 wrangler/configuration.md 中确认了该推荐意见与版本前提。一个最小的完整配置骨架如下{ $schema: ./node_modules/wrangler/config-schema.json, name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // Use current date for new projects // Bindings (non-inheritable) vars: { ENVIRONMENT: production }, kv_namespaces: [{ binding: MY_KV, id: abc123 }], r2_buckets: [{ binding: MY_BUCKET, bucket_name: my-bucket }], d1_databases: [{ binding: DB, database_name: my-db, database_id: xyz789 }], // Environments env: { staging: { vars: { ENVIRONMENT: staging }, kv_namespaces: [{ binding: MY_KV, id: staging-id }] } } }几个关键字段的作用$schema指向./node_modules/wrangler/config-schema.json提供编辑器校验与自动补全nameWorker 名称同时决定*.workers.dev子域名若启用workers_devmain入口文件路径即模块 Worker 的导出源文件compatibility_date指定运行时兼容性基准日决定哪些新特性对当前 Worker 开放。新项目务必把compatibility_date设置为当前日期如2025-01-01仅为示例这是仓库参考文档在 workers/configuration.md 中以强调语气给出的硬性建议旧日期会长期锁定旧行为新日期才能持续获得 Cloudflare 运行时的新能力。配置规则字段的继承属性在多环境env配置中Wrangler 对字段的合并行为有一套明确规则理解它是避免环境配置悄悄丢失的前提分类字段行为可继承Inheritablename、main、compatibility_date、routes、workers_dev及triggers顶层定义后各环境可覆盖未覆盖则继承顶层值不可继承Non-inheritable所有绑定vars、kv_namespaces、r2_buckets、d1_databases等每个环境必须显式声明自己的绑定不会从顶层继承仅限顶层Top-level onlymigrations、keep_vars、send_metrics只能写在顶层不能放在env中这正是不可继承字段设计的目的staging环境必须显式给出自己的 KV namespace ID如staging-id避免误用生产资源而compatibility_date这类全局行为则在顶层统一声明。此规则与 wrangler/configuration.md 中的字段继承说明相互印证。Bindings连接存储与计算资源Bindings绑定是 Worker 访问外部资源存储、队列、AI、其他 Worker的唯一声明式入口运行时通过env对象暴露。核心绑定类型与完整写法如下{ // Environment variables - access via env.VAR_NAME vars: { ENVIRONMENT: production }, // KV (key-value storage) kv_namespaces: [{ binding: MY_KV, id: abc123 }], // R2 (object storage) r2_buckets: [{ binding: MY_BUCKET, bucket_name: my-bucket }], // D1 (SQL database) d1_databases: [{ binding: DB, database_name: my-db, database_id: xyz789 }], // Durable Objects (stateful coordination) durable_objects: { bindings: [{ name: COUNTER, class_name: Counter }] }, // Queues (message queues) queues: { producers: [{ binding: MY_QUEUE, queue: my-queue }], consumers: [{ queue: my-queue, max_batch_size: 10 }] }, // Service bindings (worker-to-worker RPC) services: [{ binding: SERVICE_B, service: service-b }], // Analytics Engine analytics_engine_datasets: [{ binding: ANALYTICS }] }各绑定在运行时对应的访问方式详见 workers/api.md// KV await env.MY_KV.get(key); await env.MY_KV.put(key, value, { expirationTtl: 3600 }); // R2 const obj await env.MY_BUCKET.get(file.txt); await env.MY_BUCKET.put(file.txt, content); // D1 const result await env.DB.prepare(SELECT * FROM users WHERE id ?).bind(1).first(); // Queues await env.MY_QUEUE.send({ timestamp: Date.now() }); // Secrets/vars const key env.API_KEY;补充几个参考文档中尚未展开、但对实战至关重要的绑定细节依据 bindings/configuration.mdid与name的使用差异KV、D1 用idkv_namespaces[].id、d1_databases[].database_idR2、Queues 用namebucket_name、queue切勿混用绑定数量上限单个 Worker 的绑定总数所有类型合计上限为64 个本地开发可为 KV 等绑定补充preview_id供wrangler dev本地模拟使用或直接npx wrangler dev --remote使用真实生产资源Durable Objects 外部引用当class_name位于其他 Worker 时需显式指定script_name例如{ name: COUNTER, class_name: Counter, script_name: my-worker }并配套migrations声明如migrations: [{ tag: v1, new_sqlite_classes: [Counter] }]更多绑定类型仓库还记录了vectorize向量索引、hyperdrive现有数据库连接池PG 场景需配合nodejs_compat_v2、aiWorkers AI、workflows、secrets_store、mtls_certificates、browser浏览器渲染等可参考 bindings/configuration.md 的完整清单。Secrets永远不要写进配置文件密钥类信息严禁放入wrangler.jsonc该文件可能被提交到仓库必须通过 CLI 设置npx wrangler secret put API_KEY设置后在代码中通过env.API_KEY读取。更完整的密钥管理命令见 wrangler/README.mdnpx wrangler secret put NAME # Set Worker secret npx wrangler secret list # List Worker secrets npx wrangler secret delete NAME # Delete Worker secret npx wrangler secret bulk FILE.json # Bulk upload from JSON如需跨多个 Worker 复用集中式密钥可改用 Secrets Storewrangler secret-store:secret put STORE_NAME SECRET_NAME并在配置中声明secrets_store: [{ binding: SECRETS, id: store-id }]。自动预置Beta省略 ID 自动创建Wrangler 提供自动预置能力绑定声明中省略资源 ID部署时 Wrangler 会自动创建资源并把真实 ID 写回配置文件。{ kv_namespaces: [{ binding: MY_KV }] } // ID added on deploy部署完成后配置文件中会自动补全该绑定对应的资源 ID。该机制同样记录于 wrangler/configuration.md适合原型开发阶段快速起步生产环境仍建议先通过wrangler kv namespace create等命令显式创建资源再填入 ID。路由与触发器Worker 的对外访问入口通过routes声明定时任务通过triggers.crons声明{ routes: [ { pattern: example.com/*, zone_name: example.com } ], triggers: { crons: [0 */6 * * *] // Every 6 hours } }路由的三种形态详见 wrangler/configuration.md 的 Routing 一节// 自定义域名推荐pattern 即完整域名custom_domain 置 true { routes: [{ pattern: api.example.com, custom_domain: true }] } // 基于 Zonepattern zone_name 指向你在 Cloudflare 托管的主域名 { routes: [{ pattern: api.example.com/*, zone_name: example.com }] } // workers.dev 免费子域名无需 routes直接置 workers_dev 为 true { workers_dev: true }Cron 触发器对应 Worker 的scheduled处理器async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promisevoid { // 定时执行的逻辑例如周期性清理 }TypeScript 配置从自动类型生成到手动声明自动类型生成推荐从wrangler.jsonc自动生成绑定类型让env完全类型化npm install -D cloudflare/workers-types npx wrangler types # Generates .wrangler/types/runtime.d.ts from wrangler.jsonc配套的tsconfig.json{ compilerOptions: { target: ES2022, lib: [ES2022], types: [cloudflare/workers-types] }, include: [.wrangler/types/**/*.ts, src/**/*] }导入生成的类型并在处理器中使用import type { Env } from ./.wrangler/types/runtime; export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { await env.MY_KV.get(key); // Fully typed, autocomplete works return new Response(OK); }, };每次修改wrangler.jsonc中的绑定后务必重新执行npx wrangler types让Env类型与最新绑定保持同步。若发现类型未生成也可参考 workers/gotchas.md 的排查思路确认tsconfig.json的include已覆盖.wrangler/types/**/*.ts。手动类型定义传统方式不使用自动生成时可手写Env接口将绑定名映射到对应类型interface Env { MY_KV: KVNamespace; DB: D1Database; API_KEY: string; }这种方式要求开发者手动维护与配置的对应关系绑定增多后容易遗漏这也是官方推荐自动生成的原因。高级选项placement、Node.js 兼容与可观测性{ // Auto-locate compute near data sources placement: { mode: smart }, // Enable Node.js built-ins (Buffer, process, path, etc.) compatibility_flags: [nodejs_compat_v2], // Observability (10% sampling) observability: { enabled: true, head_sampling_rate: 0.1 } }Smart Placement就近数据源计算mode: smartWorker 自动运行在靠近数据源D1、Durable Objects 等的位置降低跨区访问延迟mode: off默认全局分布Worker 运行在用户就近的边缘节点。两种模式的行为对比详见 wrangler/configuration.md。选择依据是流量特征请求强依赖远程存储时用smart纯计算型或用例对地理分布敏感时保持off。Node.js 兼容nodejs_compat_v2启用nodejs_compat_v2后Worker 可获得Buffer、process.env、path、stream等 Node.js 内建模块CommonJSrequire()加载 Node 模块node:前缀导入如import { Buffer } from node:buffer。注意开启该标志会带来约1-2ms 的冷启动开销。参考文档明确建议能用 Workers 原生 API如 R2 存储文件、KV 做缓存时优先使用原生 API仅在确实需要 Node 生态模块时再启用兼容层如pg/postgres驱动配合 Hyperdrive。Observability 可观测性{ observability: { enabled: true, head_sampling_rate: 0.1 } }head_sampling_rate控制链路追踪的采样率0.1表示采样 10% 的请求。生产环境可据此在成本与可观测覆盖度之间取平衡。多环境部署工作流以仓库 bindings/configuration.md 的完整示例为基础生产与暂存环境应各自显式声明绑定{ name: my-worker, vars: { ENV: production }, kv_namespaces: [{ binding: CACHE, id: prod-kv-id }], env: { staging: { vars: { ENV: staging }, kv_namespaces: [{ binding: CACHE, id: staging-kv-id }] } } }对应的部署命令npx wrangler deploy # Production npx wrangler deploy --env staging npx wrangler deploy --dry-run # Validate only其中--dry-run只做配置与打包校验、不实际发布适合接入 CI 前的本地自检。更完整的版本管理命令wrangler versions list、wrangler rollback [id]与发布命令参考 wrangler/README.md。部署前置检查认证任何wrangler deploy之前先确认已认证npx wrangler whoami # Shows account if authenticated交互式本地开发wrangler login一次性 OAuthCI/CD 环境设置CLOUDFLARE_API_TOKEN环境变量。若在沙箱环境中部署因网络受限失败可参考 SKILL.md 的说明以sandbox_permissionsrequire_escalated重新执行部署。延伸阅读Workers API 与绑定运行时用法fetch 处理器、ctx.waitUntil、Cache API、HTMLRewriter、WebSocket 等运行时能力Workers 部署与开发模式错误处理、CORS、路由、性能与测试Workers 常见坑位与限制CPU 超限、流式 body 复用、Node 模块缺失等Wrangler 配置总览路由、Assets、Cron、Limits、Logpush 等更多顶层字段绑定配置全集全部绑定类型的创建命令与 Key PointsKV / D1 / R2 / Durable Objects / Queues各存储与协作服务的专项参考【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考