saas

Cloudflare Wrangler CLI 完全指南：Workers 开发、部署与调试实战

Wrangler 是 Cloudflare Workers 的官方 CLI 工具。本文详解从初始化到生产部署的完整工作流：项目创建、本地开发服务器、环境变量管理、KV/D1/R2 绑定、 secrets 配置、CI/CD 集成、调试日志与监控。附完整命令清单和 wrangler.toml 配置模板。

Leeting Yan 4 分钟阅读 1890 字

Wrangler 是 Cloudflare Workers 的官方 CLI 工具，它是 Workers 开发生态的核心：从创建项目、本地调试、管理 KV/D1/R2 绑定，到部署到全球边缘节点，全部通过 wrangler 命令完成。本文覆盖 Wrangler 从安装到生产的完整工作流。

一、安装与初始化

1.1 安装 Wrangler

# 全局安装
npm install -g wrangler

# 或作为项目 devDependency
npm install -D wrangler

# 验证安装
wrangler --version
# wrangler 3.x.x

1.2 登录 Cloudflare

wrangler login
# 浏览器打开授权页面 → 选择 Cloudflare 账号 → 授权 Wrangler

# 验证登录状态
wrangler whoami
# 输出 Account Name 和 Account ID

1.3 创建项目

# 方式一：官方模板（推荐）
npm create cloudflare@latest my-worker
# 选择：
#   - What type of application: Hello World example
#   - TypeScript: Yes
#   - git: Yes
#   - Deploy: No（稍后手动部署）

cd my-worker

# 方式二：手动创建
mkdir my-worker && cd my-worker
npm init -y
npm install -D wrangler typescript @cloudflare/workers-types

1.4 项目结构

my-worker/
├── src/
│   └── index.ts          # Worker 入口
├── wrangler.toml         # 配置文件
├── package.json
└── tsconfig.json

// src/index.ts
export interface Env {
  // 环境变量类型声明
  MY_VARIABLE: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response(`Hello, world! MY_VARIABLE=${env.MY_VARIABLE}`);
  },
};

二、wrangler.toml 配置详解

# wrangler.toml 完整模板
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-11-20"

# 部署账户
account_id = "your-account-id"

# Workers 运行时配置
[vars]
MY_VARIABLE = "production-value"
API_VERSION = "v2"

# 环境变量（开发/生产分离）
[env.staging]
name = "my-worker-staging"
vars = { MY_VARIABLE = "staging-value" }

[env.production]
name = "my-worker-production"
vars = { MY_VARIABLE = "production-value" }

# KV 命名空间绑定
[[env.production.kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# D1 数据库绑定
[[env.production.d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# R2 存储桶绑定
[[env.production.r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

# Durable Objects 绑定
[[env.production.durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"
script_name = "my-worker"

# 路由规则（自定义域名）
[[env.production.routes]]
pattern = "api.mydomain.com/*"
custom_domain = true

# 计划类型（免费/付费）
[env.production.usage_model]
mode = "bundled"   # bundled = 付费 Workers (最少 $5/月)
# mode = "unbound" # unbound = 按量计费（无最低，适合低频）

三、本地开发

3.1 启动本地服务器

# 开发模式（热重载）
wrangler dev

# 指定环境
wrangler dev --env staging

# 指定远程资源（用真实的 KV/D1 数据）
wrangler dev --remote

# 指定端口
wrangler dev --port 8787

# 同时绑定多个资源
wrangler dev --kv MY_KV --d1 DB --r2 MY_BUCKET

本地服务器启动后：

  • 访问 http://localhost:8787 测试 Worker
  • 修改代码后自动热重载
  • 支持 console.log 输出到终端

3.2 使用 Miniflare 模拟本地资源

# 创建本地 KV 命名空间
wrangler kv:namespace create "MY_KV" --local

# 写入本地 KV
wrangler kv:key put --namespace-id=<id> "my-key" "my-value" --local

# 创建本地 D1 数据库
wrangler d1 create my-local-db --local

# 执行本地 D1 迁移
wrangler d1 execute my-local-db --file=./schema.sql --local

3.3 调试技巧

# 查看 Worker 日志
wrangler tail

# 指定环境查看日志
wrangler tail --env production

# 格式化 JSON 日志
wrangler tail --format json

# 只查看特定级别的日志
wrangler tail --debug

四、部署

4.1 首次部署

# 部署到默认环境
wrangler deploy

# 部署到特定环境
wrangler deploy --env production

# 部署到具体路由
wrangler deploy --routes "api.mydomain.com/*"

部署输出：

✨ Successfully published your script to:
  https://my-worker.your-subdomain.workers.dev

4.2 CI/CD 集成

GitHub Actions 示例：

# .github/workflows/deploy.yml
name: Deploy Worker
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

// package.json
{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "deploy:prod": "wrangler deploy --env production",
    "tail": "wrangler tail",
    "db:migrate": "wrangler d1 migrations apply my-db --remote"
  }
}

4.3 API Token 配置

# 在 Cloudflare Dashboard → My Profile → API Tokens → Create Token
# 使用 "Edit Cloudflare Workers" 模板
# 赋予 Zone:Read + Script:Edit + Account:Read 权限

# 配置 Wrangler 使用 Token
wrangler config
# 或直接设置环境变量
export CLOUDFLARE_API_TOKEN=your-token

五、Secrets 管理

# 设置 Secret（加密存储）
wrangler secret put API_KEY
# 交互式输入 secret 值

# 批量设置（从文件）
echo "my-secret" | wrangler secret put API_KEY

# 查看 Secrets 列表
wrangler secret list

# 删除 Secret
wrangler secret delete API_KEY

# 指定环境
wrangler secret put API_KEY --env production

⚠️ Secrets 与 wrangler.toml 中 [vars] 的区别：

  • [vars]：明文存储，适合非敏感配置，版本控制可见
  • Secrets：加密存储，适合 API Key/Token，版本控制不可见

六、KV 操作命令速查

# 创建命名空间
wrangler kv:namespace create "MY_STORE"
# 输出：binding = "MY_STORE", id = "xxxxx"

# 列出命名空间
wrangler kv:namespace list

# 写入键值
wrangler kv:key put --namespace-id=<id> "user:123" '{"name":"Alice"}'

# 写入 expires（TTL）
wrangler kv:key put --namespace-id=<id> "session:abc" "data" --expiration 3600

# 读取键值
wrangler kv:key get --namespace-id=<id> "user:123"

# 删除键值
wrangler kv:key delete --namespace-id=<id> "user:123"

# 列出所有键
wrangler kv:key list --namespace-id=<id> --prefix "user:"

# 批量操作（JSON 文件）
# data.json: [{"key":"k1","value":"v1"},{"key":"k2","value":"v2"}]
wrangler kv:bulk put --namespace-id=<id> ./data.json

# 查看用法统计
wrangler kv:namespace usage --namespace-id=<id>

七、D1 数据库操作速查

# 创建数据库
wrangler d1 create my-database

# 列出数据库
wrangler d1 list

# 执行 SQL
wrangler d1 execute my-database --command "SELECT * FROM users"

# 执行 SQL 文件（迁移）
wrangler d1 execute my-database --file=./migrations/001_init.sql

# 创建迁移
wrangler d1 migrations create my-database "add_posts_table"

# 应用迁移（本地）
wrangler d1 migrations apply my-database --local

# 应用迁移（远程）
wrangler d1 migrations apply my-database --remote

# 导出数据库
wrangler d1 export my-database --remote --output=./backup.sql

# 查看数据库信息
wrangler d1 info my-database

八、Workers 版本管理

# 查看已部署版本
wrangler versions list

# 查看版本详情
wrangler versions view <version-id>

# 回滚到指定版本
wrangler rollback <version-id>

# 流量切分（灰度发布）
# 将 10% 流量切到新版本
wrangler versions deploy <version-id> --percentage 10

# A/B 测试：50/50 流量分配
wrangler versions deploy <version-id> --percentage 50

九、常见问题（FAQ）

wrangler dev 启动报错 “No such file or directory”

检查 wrangler.toml 中的 main 字段是否指向正确的入口文件。如果使用 npm create cloudflare 创建的项目，入口通常是 src/index.ts。

环境变量在部署后读取不到

确认：

  1. wrangler.toml 中 [vars] 或 [env.*.vars] 是否正确配置
  2. TypeScript 类型定义中是否声明了对应属性：interface Env { MY_VAR: string; }
  3. 如果使用 wrangler deploy --env production，确认 production 环境的 vars 已配置

本地开发正常，部署后 500

排查步骤：

  1. wrangler tail 查看远程错误日志
  2. 检查 Secrets 是否已部署（本地 dev 可能用 --local 但生产需要 --remote）
  3. 确认 KV/D1/R2 的 binding ID 在生产环境是否正确
  4. 检查 compatibility_date 是否过旧

如何共享 Workers 之间的代码？

使用 Service Bindings：

# wrangler.toml
[[services]]
binding = "USER_SERVICE"
service = "user-worker"

// 在另一个 Worker 中调用
const userResponse = await env.USER_SERVICE.fetch('/users/123');

Wrangler 2 和 3 有什么区别？

Wrangler 3 是 2023 年发布的大版本，主要变化：

  • 使用本地 Miniflare 代替 --local
  • 默认 Workers Paid（付费）模式，Free tier 需要显式声明
  • 改进了 wrangler dev 的热重载
  • 新版 Secrets 管理（wrangler secret v3）
  • 推荐所有新项目使用 Wrangler 3

相关阅读

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「saas」更多文章

自定义域名接入 Cloudflare：CDN 加速与缓存规则配置实战 手把手讲解自定义域名接入 Cloudflare CDN 的完整流程：NS 接管、SSL/TLS 模式选择、橙云代理与灰云 DNS 的区别，并用 2024 年后的新 Cache Rules 引擎实战配置静态资源长缓存、HTML 不缓存、后台 Bypass，让边缘缓存命中率最大化。 Hugo 部署到 Cloudflare Pages 实战：从 Git 推送到全球边缘上线 详解 Cloudflare Pages 部署 Hugo 静态站的完整流程，涵盖框架预设、HUGO_VERSION 环境变量固定、构建命令、自定义域名、分支预览、_headers 缓存安全头配置及常见构建失败排查，一次推送即可全球边缘上线。 Cloudflare Workers 入门实战：在边缘运行你的第一行代码 一份面向初学者的 cloudflare workers 教程，从 V8 Isolate 运行时模型讲起，手把手演示 wrangler 初始化、路由分发、KV 存储、Cache API 缓存响应与环境变量配置，帮你在 30 分钟内部署第一个生产可用的边缘 Serverless 应用。