Cloudflare Workers 部署指南：用 C3 和 Wrangler 发布边缘应用

Workers 的官方 CLI 入门路径由 C3 和 Wrangler 组成：C3 创建项目和初始配置，Wrangler 负责本地开发、配置解析和发布。下面的路径适合第一次部署一个轻量 Worker；已有仓库可以保留现有代码，再补齐 Wrangler 配置和绑定。

前置条件

• 一个 Cloudflare 账户，必要时准备 Account ID。
• Node.js 和 npm。
• 一个独立的项目目录，以及明确的入口文件和运行时语言。
• 如果使用 KV、D1 或 R2，先设计资源名称、环境隔离、迁移和备份策略。

部署路径

在项目目录执行 C3 创建命令：

npm create cloudflare@latest -- my-first-worker
cd my-first-worker

官方入门流程会要求选择示例、模板、语言、Git 和是否立即部署。第一次学习时可以先选择 Hello World、Worker only、JavaScript、启用 Git，并选择暂不部署，以便先检查生成的文件。

开发阶段运行：

npx wrangler dev

Wrangler 会启动本地预览；首次使用可能打开浏览器进行 Cloudflare 登录。确认入口代码和本地绑定行为后，再执行：

npx wrangler deploy

发布时可以使用 workers.dev 子域名或自定义域名。自定义域名、路由和 DNS 是独立配置边界，不能仅凭命令返回成功就认为域名已经可用。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    A[源代码] --> C3[C3 创建项目]
    C3 --> W[Wrangler 配置]
    W --> DEV[wrangler dev 本地预览]
    DEV --> TEST[代码与绑定验收]
    TEST --> DEPLOY[wrangler deploy]
    DEPLOY --> SUB[workers.dev]
    DEPLOY --> DOMAIN[自定义域名]

配置与绑定

Workers 的配置文件应固定入口、兼容的兼容性日期、环境和部署目标。绑定是权限和 API 的组合，代码从 env 取得资源，不要把资源密钥硬编码到 Worker。

{
  "main": "src/index.js",
  "compatibility_date": "2026-09-15",
  "workers_dev": true,
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "<bucket-name>" }
  ]
}

示例只说明配置形状，<bucket-name> 不是可直接使用的资源。D1、KV 和 R2 要分别记录绑定名、资源角色、migration、备份和恢复边界。开发环境默认可以使用本地模拟资源，也可以在明确授权后配置 Remote Bindings 访问真实资源。

验收

文档级部署准备至少包括：

1. wrangler dev 能启动本地预览，并能看到入口函数的预期响应。
2. 配置文件中的入口路径、兼容性日期和绑定名称与代码一致。
3. 发布后在 Dashboard 中确认部署版本，并访问 workers.dev 或配置的域名。
4. 使用 curl -i https://<worker-subdomain>.workers.dev 检查状态码和响应体。
5. 需要数据资源时，分别验证读取、写入、权限和迁移结果；只看到 Worker 响应成功不等于 D1、KV 或 R2 数据正确。

本篇没有运行 Wrangler、创建资源或执行远程部署，验证等级为 documented。实际发布应另行记录命令输出、版本、域名和资源验收结果。

回滚边界

• 保留上一个可用提交、配置和绑定清单，才能重建旧版本。
• 代码版本回滚不会自动回滚 D1 schema、KV 内容或 R2 对象；不可逆 migration 需要前置备份和兼容窗口。
• workers.dev 地址、Custom Domain、Routes 和 DNS 的变更分别记录，域名回滚不能代替代码回滚。
• 生产发布建议把构建、预览、批准、发布和验收拆成独立步骤，并让 CI 使用最小权限 Token。

参考资料

• Workers CLI 入门
• Workers Bindings
• Workers 自定义域名