Cloudflare C3 生成配置完全指南wrangler.jsonc、绑定占位符与类型生成实战解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文围绕 Cloudflare 官方脚手架工具 C3create-cloudflare生成的项目配置文件展开逐项拆解 C3 输出目录结构、wrangler.jsonc配置语义、KV/D1 绑定占位符的替换流程、package.json脚本约定与wrangler types类型生成机制并结合本仓库 C3 配置文档 及 Wrangler 配置参考 等源码级资料做纵深补充。读完你将能够看懂 C3 生成的每个文件的用途、正确替换绑定占位符完成首次部署、通过cf-typegen让绑定在 TypeScript 中类型安全并掌握一套可复用的部署前自检清单。一、C3 是什么理解生成配置的源头C3create-cloudflare是 Cloudflare 官方的项目脚手架 CLI用于基于模板快速创建 Workers 与 Pages 项目默认携带 TypeScript 支持并可直接部署。本仓库 C3 参考索引 中将其定义为 Official CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment。理解 C3 生成配置之前先看它的两种典型调用方式详见 C3 CLI 参考# WorkerAPI/WebSocket/Cron 等 npm create cloudflarelatest my-api -- --typehello-world --langts # Pages静态站点/SSG/全栈 npm create cloudflarelatest my-site -- --typeweb-app --frameworkastro --platformpages关键注意点Pages 项目必须显式加--platformpages否则 C3 默认按 Workers 生成。这也是本仓库 C3 README 中标注为 Critical 的平台选择规则。C3 以非交互方式运行时依赖--type、--framework、--ts/--no-ts、--no-git、--no-deploy等参数避免在 CI 中挂起这一行为与后文「部署前自检清单」中建议的 CI 参数组合直接相关。二、C3 生成的项目输出结构C3 创建完项目后会生成如下目录骨架来自 C3 配置文档my-app/ ├── src/index.ts # Worker 入口 ├── wrangler.jsonc # Cloudflare 配置文件 ├── package.json # 脚本Scripts ├── tsconfig.json └── .gitignore各文件职责文件职责src/index.tsWorker 入口文件默认导出fetch处理器通过Env接口访问绑定wrangler.jsoncWrangler 配置文件推荐格式自带 schema 校验详见下文package.json项目脚本与依赖管理dev/deploy/cf-typegentsconfig.jsonTypeScript 编译配置配合生成的类型声明使用.gitignore忽略.wrangler/、node_modules/等目录值得强调的是C3 默认采用wrangler.jsonc而非旧版wrangler.toml。本仓库 Wrangler 配置参考 明确说明wrangler.jsonc是 Wrangler v3.91.0 之后推荐使用的格式核心优势是提供配置 schema 校验借助$schema字段编辑器可实时提示与纠错。三、wrangler.jsonc 核心字段解读C3 生成的wrangler.jsonc最小化配置如下{ $schema: https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json, name: my-app, main: src/index.ts, compatibility_date: 2026-01-27 }字段语义结合 Wrangler 配置参考 扩充$schemaJSONC 的 schema 地址用于编辑器的自动补全与校验。本地项目也可以改为相对路径形式./node_modules/wrangler/config-schema.json。nameWorker 名称同时影响部署后的 workers.dev 子域名与后续路由绑定。部署报错 Worker already exists 时修改此处即可解决见 C3 故障排查。mainWorker 入口文件路径默认指向src/index.ts。compatibility_date指定 Wrangler 运行时兼容性基准日期。若运行时报错Feature X requires compatibility_date ...需要将其更新为当天的日期见 C3 故障排查。在此基础上可以按需扩展以下配置区块均可在 Wrangler 配置参考 中找到完整写法{ vars: { API_KEY: dev-key }, // 明文变量 kv_namespaces: [{ binding: MY_KV, id: abc123 }], // KV 命名空间绑定 d1_databases: [{ binding: DB, database_id: abc-123 }], // D1 数据库绑定 r2_buckets: [{ binding: ASSETS, bucket_name: my-assets }], // R2 存储桶 routes: [{ pattern: api.example.com, custom_domain: true }], // 自定义域名 workers_dev: true // 启用 *.workers.dev }3.1 字段继承与多环境Wrangler 配置参考 特别指出name、main、compatibility_date、routes、triggers是可继承字段而vars、各类绑定KV、D1、R2 等不可继承必须按环境单独定义。典型的多环境配置{ 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即可切换到对应环境配置。四、绑定占位符部署前必须替换的坑这是 C3 生成配置中最容易踩坑、也是原文档重点强调的部分。当项目通过交互式流程或在模板中声明了 KV / D1 等资源时C3 生成的wrangler.jsonc中会包含占位 IDplaceholder IDs{ kv_namespaces: [{ binding: MY_KV, id: placeholder_kv_id }], d1_databases: [{ binding: DB, database_id: 00000000-... }] }4.1 为什么必须替换占位 ID 不是真实资源标识符。如果带着占位 ID 直接执行wrangler deploy会在部署阶段立即报错本仓库 C3 配置文档 原文给出的错误信息Error: Invalid KV namespace ID placeholder_kv_id4.2 如何获取真实 ID通过 Wrangler CLI 创建真实资源并取回 ID替换占位符npx wrangler kv namespace create MY_KV # 返回真实 id npx wrangler d1 create my-database # 返回真实 database_id对应的资源创建与查询命令在 绑定配置参考 中有完整列表npx wrangler r2 bucket create my-bucket npx wrangler vectorize create my-index --dimensions768 --metriccosine npx wrangler queues create my-queue # 列出已有资源 npx wrangler kv namespace list npx wrangler d1 list npx wrangler r2 bucket list4.3 本地开发与生产环境的区分如果希望本地开发wrangler dev使用独立的 KV 命名空间可借助preview_id见 KV 配置参考{ kv_namespaces: [ { binding: MY_KV, id: prod-id, preview_id: dev-id } ] }也可以直接用wrangler dev --remote让本地开发连接生产绑定见 绑定配置参考。注意本仓库 Wrangler 配置参考 还介绍了 Auto-ProvisioningBeta能力省略资源id后Wrangler 会在部署时自动创建资源并把真实 ID 回写进配置文件。如果你的 Wrangler 版本支持该 Beta 特性这可以替代手动替换占位符的流程。五、package.json 脚本约定C3 生成的三条核心脚本来自 C3 配置文档{ scripts: { dev: wrangler dev, deploy: wrangler deploy, cf-typegen: wrangler types } }各脚本在项目生命周期中的角色脚本等价命令用途npm run devwrangler dev本地开发默认带热重载可加--remote连接生产资源npm run deploywrangler deploy部署到 Cloudflare 边缘网络npm run cf-typegenwrangler types根据wrangler.jsonc中的绑定生成 TypeScript 类型声明本仓库 C3 README 的 Post-Creation 章节给出的典型使用顺序是cd my-app npm run dev # 本地热重载开发 npm run cf-typegen # 为绑定生成 TypeScript 类型 npm run deploy # 部署到 Cloudflare5.1 部署前先认证SKILL.md 总览 强调执行wrangler deploy/npm run deploy之前必须完成认证可用npx wrangler whoami验证当前登录状态。未认证时的处理方式本地/交互式环境npx wrangler login一次性 OAuth 登录CI/CD 环境设置CLOUDFLARE_API_TOKEN环境变量详见 C3 CLI 参考。六、类型生成cf-typegen 与 Env 接口6.1 生成机制在添加绑定或修改wrangler.jsonc中的绑定配置之后运行npm run cf-typegen该命令会基于当前wrangler.jsonc中的绑定声明生成.wrangler/types/runtime.d.ts文件内容形如来自 C3 配置文档interface Env { MY_KV: KVNamespace; DB: D1Database; }Env接口随后作为 Worker 的fetch处理器第二个参数的类型让env.MY_KV、env.DB在编辑器中获得完整的类型提示与编译期检查。6.2 类型化使用示例KV 配置参考 给出了绑定在代码中的典型用法export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { // env.MY_KV 现在被类型化为 KVNamespace const value await env.MY_KV.get(key); return new Response(value || Not found); } } satisfies ExportedHandlerEnv;D1 绑定同理见 D1 配置参考interface Env { DB: D1Database; } export default { async fetch(request: Request, env: Env): PromiseResponse { const result await env.DB.prepare(SELECT * FROM users).all(); return Response.json(result.results); } }6.3 常见类型问题排查C3 故障排查 中针对类型问题给出了两条高频解决方案报错Cannot find name KVNamespace重新运行npm run cf-typegen生成类型然后重启编辑器的 TS Server类型声明文件新增后需要刷新索引修改配置后类型不同步配置变更后必须重新执行npm run cf-typegen。七、部署前自检清单Post-Creation Checklist原文档末尾给出的完整部署前自检清单此处完整继承并补充每步的验证要点Reviewwrangler.jsonc检查name是否冲突、compatibility_date是否为最新日期必要时补充routes/workers_dev等字段字段语义见第三节替换绑定占位 IDnpx wrangler kv namespace create MY_KV、npx wrangler d1 create my-database获取真实 ID 并写入配置否则部署会报Invalid KV namespace ID placeholder_kv_id运行npm run cf-typegen确保.wrangler/types/runtime.d.ts与当前绑定一致让Env接口类型完整本地测试npm run dev验证入口逻辑与绑定访问必要时用--remote联调生产资源部署npm run deploy部署前用npx wrangler whoami确认认证状态添加 Secretsnpx wrangler secret put SECRET_NAME——敏感信息永远不要写入wrangler.jsonc见 绑定配置参考 的 Key PointsSecrets 一律用wrangler secret put禁止提交到仓库。本仓库 C3 使用模式 中的清单与此一致并补充了「创建绑定」步骤wrangler kv namespace create、wrangler d1 create、wrangler r2 bucket create。7.1 CI 场景下的非交互式部署在 GitHub Actions 等 CI 环境中C3 脚手架与部署流程需要避免交互提示挂起。非交互式部署必须显式提供见 C3 使用模式--typevalue # 必填 --no-git # 推荐CI 中已在 git 仓库内 --no-deploy # 单独部署配合 Secrets 使用 --frameworkvalue # web-app 类型必填 --ts / --no-ts # 必填CI 中的认证与部署片段- name: Deploy run: npm run deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}八、从生成配置到平台能力的扩展路径C3 生成的wrangler.jsonc是连接 Workers 运行时与 Cloudflare 全平台能力的枢纽。在替换完占位符、跑通首次部署后可沿以下路径继续扩展均可通过向wrangler.jsonc追加配置块实现存储类绑定KV键值、D1关系型 SQLite、R2对象存储、Queues消息队列、Vectorize向量索引——完整写法见 绑定配置参考计算类绑定Service Bindings服务间调用、Workers AIai绑定、Workflows、Durable Objects——见 Wrangler 配置参考静态资源assets配置块directory、html_handling、not_found_handling可替代旧版site配置可观测性observability开启 tracing、triggers.crons配置定时任务、logpush将日志流转发至 R2/S3。绑定数量上限提醒绑定配置参考 的 Key Points 指出所有类型绑定合计上限为64 个规划项目时应有所预留。九、快速排错速查表结合 C3 故障排查与生成配置强相关的常见错误与修复方法汇总如下错误现象原因修复方式Invalid namespace ID绑定仍是占位符 ID创建真实资源并更新wrangler.jsoncNot authenticated未登录npx wrangler login或设置CLOUDFLARE_API_TOKENWorker already existsWorker 名称冲突修改wrangler.jsonc中的nameCannot find name KVNamespace缺少类型声明npm run cf-typegen并重启 TS ServerFeature X requires compatibility_date ...兼容日期过旧将compatibility_date更新为当天日期Node.js version not supported本地 Node 版本过低安装 Node.js 18如nvm install 20十、小结C3 生成配置的核心要点可以概括为一句话C3 只负责把项目骨架与配置文件立起来真正的资源 ID、类型声明与部署认证需要开发者按清单逐项补齐。掌握wrangler.jsonc的字段语义name/main/compatibility_date/ 各类绑定、绑定占位符的替换流程kv namespace create/d1 create、cf-typegen的类型生成机制Env接口以及部署前六步自检清单即可在 CI 与本地环境中稳定、可重复地完成 Cloudflare Worker/Pages 项目的配置、测试与上线。延伸阅读仓库内资料C3 配置文档本文主体C3 CLI 参考完整命令行参数C3 使用模式CI/CD、Monorepo、自定义模板C3 故障排查部署错误与修复Wrangler 配置参考完整配置字段与多环境绑定配置参考各类绑定的创建命令与上限KV 配置参考 与 D1 配置参考【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考