Cloudflare Workers + Wrangler 完全入门指南：从初始化到部署

Wrangler 是 Cloudflare 官方推出的命令行工具，用于创建、开发和部署 Workers 项目。无论你是想搭建一个简单的 API 接口，还是构建复杂边缘计算应用，Wrangler 都是绕不开的核心工具。本文将从零开始，带你掌握 Wrangler 的完整工作流。

前置准备

在开始之前，你需要两样东西：一个 Cloudflare 账户，以及 Node.js 环境。Wrangler 要求 Node.js 版本 16.17.0 或更高，建议使用 nvm 或 Volta 这类版本管理工具来避免权限问题。

一、安装

Wrangler 需要 Node.js 16.17.0 或更高版本。推荐用 C3 创建项目，它会自动安装最新版 Wrangler：

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

按提示选择 Hello World 模板、Worker only、JavaScript。完成后进入目录：

cd my-first-worker

生成的核心文件：

• wrangler.jsonc：配置文件
• src/index.js：入口代码
• package.json：依赖配置

二、本地开发

npx wrangler dev

首次运行会引导登录 Cloudflare。之后在 http://localhost:8787 启动本地服务，保存代码自动热重载。

想用真实边缘环境（含真实绑定资源）调试，加 --remote：

npx wrangler dev --remote

三、核心配置

wrangler.jsonc 中部署必填的三个字段：

{
  "name": "my-first-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-04-01"
}

普通变量用 vars，敏感信息用 secret 命令：

npx wrangler secret put API_KEY
npx wrangler secret list

四、部署

npx wrangler deploy

部署前可预检，不上传只验证构建：

npx wrangler deploy --dry-run --outdir=dist

五、日志与回滚

# 实时日志
npx wrangler tail

# 回滚到上一版本
npx wrangler rollback

# 查看部署记录
npx wrangler deployments list

六、TypeScript 类型生成

npx wrangler types

自动生成 Env 接口和绑定类型，访问 env.MY_KV 时有完整提示。

七、资源管理命令

# KV
npx wrangler kv namespace create CACHE
npx wrangler kv key put --namespace-id <id> "key" "value"
npx wrangler kv key get --namespace-id <id> "key"

# R2
npx wrangler r2 bucket create my-files
npx wrangler r2 object put my-files/file.txt --file ./local.txt

# D1
npx wrangler d1 create my-database
npx wrangler d1 execute my-database --command "SELECT * FROM users" --remote

八、常用标志

可在 package.json 中简化命令：

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "tail": "wrangler tail"
  }
}

九、典型开发循环

npm run dev                # 本地开发
npx wrangler secret put X  # 设置密钥
npx wrangler deploy        # 部署
npx wrangler tail          # 看日志
npx wrangler rollback      # 出问题回滚

核心原则：wrangler.jsonc 是配置的唯一来源，尽量别在控制面板手动改，否则下次部署会被覆盖。