Cloudflare Workers 开发工作流
从这一篇开始，开发方式从仪表盘切换到命令行。先学习创建项目的标准方式，理解项目结构和配置文件，再掌握本地实时预览。
用 C3 创建项目
Cloudflare 官方提供了脚手架工具 C3（create-cloudflare），一条命令就能创建标准项目结构
npm create cloudflare@latest my-worker命令运行后会依次询问几个问题
| 提示 | 建议选择 |
|---|---|
| 模板类型 | Hello World |
| 开发语言 | JavaScript（新手先不碰 TS） |
| 是否立即部署 | 先选 No，后面自己部署 |
| 是否使用 Git | 按自己习惯，推荐 Yes |
创建完成后进入项目目录
cd my-worker项目结构
用编辑器打开项目，目录结构如下
my-worker/
├── src/
│ └── index.js # Worker 代码入口
├── test/
│ └── index.spec.js # 测试文件（本教程暂不用）
├── package.json # 项目依赖和脚本
├── wrangler.toml # Worker 配置文件
└── node_modules/ # 依赖包目录新手阶段只需要关注三个文件，src/index.js 写代码，wrangler.toml 做配置，package.json 管脚本。
wrangler.toml 配置讲解
打开 wrangler.toml，内容大致如下
name = "my-worker"
main = "src/index.js"
compatibility_date = "2026-01-01"三个核心配置项的含义
| 配置项 | 作用 |
|---|---|
name |
Worker 名称，决定 workers.dev 子域名前缀 |
main |
代码入口文件路径 |
compatibility_date |
运行时兼容日期，决定使用哪个版本的平台行为 |
compatibility_date 值得多说一句。Workers 平台功能会不断演进，部分行为变化可能影响已有代码，这个日期就是代码和平台行为的”契约”，固定它之后行为就不会突然改变。后续章节添加 KV、D1 绑定，都是往这个文件里加配置块。
新版 C3 生成的文件名可能是 wrangler.jsonc，格式略有差异但作用相同，本教程统一用 wrangler.toml 讲解。
本地实时预览
启动本地开发服务器
wrangler dev命令执行后，Wrangler 会启动一个模拟线上环境的本地服务，输出类似
Ready on http://localhost:8787打开浏览器访问 http://localhost:8787，就能看到 Hello World 页面。这个本地服务的行为和线上 Workers 几乎完全一致，KV、D1、环境变量等资源也能在本地模拟。
现在修改 src/index.js 里的返回内容，保存后终端会自动检测文件变化并重新加载，刷新浏览器即可看到最新效果，这就是热更新，改一行代码立刻见效，不用反复部署。
用 curl 也可以快速验证
curl http://localhost:8787/远程模式
wrangler dev 默认在本地模拟环境运行，如果你需要调试真实线上的资源（比如读取线上 KV 的数据、测试线上密钥），可以加参数
wrangler dev --remote--remote 模式会直接使用账号里真实的绑定资源，方便排查线上才出现的问题。日常开发推荐先用默认的本地模式，速度快且不消耗线上配额。
停止开发服务器
在运行 wrangler dev 的终端按 Ctrl + C 即可停止。
提交代码
项目自带了 .gitignore，里面已排除 node_modules、.wrangler 等目录。如果项目用 Git 管理，直接提交即可。注意检查 src/index.js 里不要出现真实的密钥，密钥管理的正确姿势在 Cloudflare Workers 环境变量与密钥管理 讲解。