企业官网建设流程全解析

Cloudflare Wrangler 配置完全指南：wrangler.jsonc 从入门到进阶

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇指南以 cloudflare-deploy 技能中 Wrangler 配置参考 为核心，系统讲解 Workers 部署的核心配置文件wrangler.jsonc（推荐格式）：包括配置格式与字段继承规则、多环境管理、路由、全部类型的 Bindings（KV / D1 / R2 / Durable Objects / Service Bindings / Queues / Vectorize / Hyperdrive / Workers AI / Workflows / Secrets Store 等）、静态资源托管、Smart Placement、自动预置（Auto-Provisioning）以及 Cron、Observability、mTLS、Logpush 等进阶能力。读者学完后能够独立编写一套可部署、可多环境复用的 Wrangler 配置文件，并理解配置项背后的运行时行为。

为什么使用 wrangler.jsonc？

wrangler.jsonc是 Wrangler（Cloudflare Workers 官方 CLI）自 v3.91.0 起推荐的配置文件格式。相比旧的wrangler.toml，JSONC（JSON with Comments）最大的优势是支持 schema 校验：借助编辑器插件读取$schema字段，即可在编写配置时获得字段名、类型与取值范围的即时提示与错误检测，显著降低手写配置的出错率。

安装 Wrangler 并初始化项目后即可开始编写配置（详见 Wrangler README）：

npm 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" }] }

各字段说明：

compatibility_date 为什么重要

compatibility_date决定了 Workers 运行时为你启用哪些行为变更，是配置中最容易忽略却影响最大的字段之一。在 gotchas.md 的「Unexpected runtime changes」一节中明确将「Missing compatibility_date」列为运行时行为突变的根因。实践上：新项目填写创建当天的日期，升级依赖时按官方迁移指引逐步推进日期。

字段继承规则（Field Inheritance）

多环境配置（env字段）下，Wrangler 对顶层字段采取「可继承 / 不可继承」两种策略：

• 可继承（Inheritable）：name、main、compatibility_date、routes、triggers。子环境若不显式声明，则自动继承顶层的值，也可按需覆盖。
• 不可继承（Non-inheritable）：vars、以及各类绑定（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块内。

路由配置（Routing）

Wrangler 支持三种路由方式，可按需组合：

// 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

// D1：SQLite 关系型数据库 { "d1_databases": [{ "binding": "DB", "database_id": "abc-123" }] } // R2：S3 兼容对象存储 { "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }] }

对应资源创建命令（README.md）：

wrangler 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-assets

Durable 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 内的本地 DO，script_name可省略（见 gotchas.md「Durable Object binding not working」）。新引入的 DO 类必须通过migrations.new_sqlite_classes声明，否则部署会失败。

Service Bindings（Worker 间调用）

{ "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）。

Constellation（AI 推理）

{ "constellation": [{ "binding": "MODEL", "project_id": "proj-id" }] }

绑定命名要点

• binding是代码中的变量名（如env.MY_KV），id/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-Provisioning（Beta）：免填资源 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 Limits：CPU 时间上限（毫秒） { "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），二者可以互补使用。

结合源码与测试：配置如何驱动开发闭环

配置的价值不止于部署，它同时驱动本地开发、类型生成与集成测试三个环节：

1. 本地开发：wrangler dev直接读取wrangler.jsonc模拟运行时，wrangler dev --remote则按配置访问真实远端资源（见 patterns.md）；
2. 类型生成：运行wrangler types基于配置生成worker-configuration.d.ts，让env.MY_KV等绑定在 TypeScript 中获得完整类型提示：

   export default { async fetch(request: Request, env: Env): Promise<Response> { return Response.json({ value: await env.MY_KV.get("key") }); } } satisfies ExportedHandler<Env>;

   官方建议在每次修改配置后重新执行wrangler types（见 api.md Best Practices）；

3. 集成测试：Wrangler 的编程 APIstartWorker可直接传入config: "wrangler.jsonc"启动带真实本地绑定的 Worker 实例，配合environment、remote等选项覆盖不同环境（api.md）：

   import { startWorker } from "wrangler"; const worker = await startWorker({ config: "wrangler.jsonc", environment: "development", remote: "minimal" // 快速测试 + 真实远端绑定 }); // worker.fetch(...) 发起请求断言 await worker.dispose(); // 必须清理，防止资源泄漏

配置排错速查（常见陷阱）

结合 gotchas.md，整理配置相关的高频问题与对策：

延伸阅读

• Wrangler 总览与常用命令：安装、init/dev/deploy、KV/D1/R2 资源管理、secret 与 tail
• Wrangler 编程 API：startWorker、getPlatformProxy、事件系统与动态重配置
• Wrangler 开发模式：New Worker、本地开发、D1 迁移、Vitest 测试与多 Worker 联调
• Wrangler 常见问题：错误清单、限额表与排错命令
• Wrangler 认证配置：wrangler login与 CI/CD 的 API Token
• cloudflare-deploy 技能入口：按场景选择产品并加载对应参考资料

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills