使用 Wrangler CLI 在本地开发和调试 Cloudflare Worker 与 Pages 项目，不花一分钱就能跑通全流程。

环境准备

# 安装 Wrangler（Cloudflare 官方 CLI）
npm install -g wrangler

# 验证版本
wrangler --version

# 登录 Cloudflare 账号（会打开浏览器授权）
wrangler login

# 验证登录状态
wrangler whoami

---

Worker 本地开发

创建项目

# 交互式创建（推荐，可选模板）
wrangler init my-worker

# 指定模板
wrangler init my-worker --template hello-world

生成的项目结构：

my-worker/
├── src/
│   └── index.js      # Worker 入口
├── wrangler.toml     # 配置文件
├── package.json
└── tsconfig.json     # 如果选了 TypeScript

配置文件

# wrangler.toml
name = "my-worker"
main = "src/index.js"
compatibility_date = "2025-03-26"

# 路由绑定（可选）
# route = { pattern = "api.example.com/*", zone_name = "example.com" }

最简 Worker

// src/index.js
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)

    if (url.pathname === "/api/hello") {
      return Response.json({ message: "Hello from Worker!" })
    }

    return new Response("Not Found", { status: 404 })
  },
}

本地运行

# 启动本地开发服务器（默认 http://localhost:8787）
wrangler dev

# 指定端口
wrangler dev --port 3000

# 模拟远程环境（连接 Cloudflare 网络执行，能访问 KV、D1 等绑定资源）
wrangler dev --remote

本地模式 vs 远程模式：

模式	命令	执行位置	绑定资源
本地	wrangler dev	本地机器	使用本地模拟（Miniflare）
远程	wrangler dev --remote	Cloudflare 边缘	连接真实 KV、D1、R2 等

开发阶段推荐本地模式，需要调试真实资源时切 --remote。

调试

# 启动时开启详细日志
wrangler dev --log-level debug

# Worker 内使用 console.log 输出，终端实时显示

// src/index.js
export default {
  async fetch(request, env, ctx) {
    console.log("请求路径:", new URL(request.url).pathname)
    console.log("请求方法:", request.method)
    return new Response("ok")
  },
}

部署

# 部署到 Cloudflare
wrangler deploy

# 查看部署状态
wrangler deployments list

---

Pages 本地开发

Pages 适合部署静态站点和全栈应用（通过 Functions 提供后端能力）。

创建项目

# 创建 Pages 项目
npx create-cloudflare@latest my-pages --framework=none

# 常见框架模板
npx create-cloudflare@latest my-blog --framework=astro
npx create-cloudflare@latest my-app --framework=next
npx create-cloudflare@latest my-site --framework=vue
npx create-cloudflare@latest my-site --framework=hugo

项目结构

my-pages/
├── public/             # 静态文件（HTML/CSS/JS）
│   └── index.html
├── functions/          # Pages Functions（后端 API）
│   └── api/
│       └── hello.js
├── wrangler.toml       # 配置文件
└── package.json

Pages Functions

// functions/api/hello.js
// 文件路径即路由：/api/hello
export async function onRequestGet(context) {
  const { request, env, params } = context

  return Response.json({
    message: "Hello from Pages Functions!",
    url: request.url,
  })
}

// POST 请求
export async function onRequestPost(context) {
  const body = await context.request.json()
  return Response.json({ received: body })
}

本地运行

# 启动本地开发服务器（默认 http://localhost:8788）
wrangler pages dev ./public

# 指定端口
wrangler pages dev ./public --port 3000

# 带 Functions 运行（自动加载 functions/ 目录）
wrangler pages dev ./public --compatibility-date=2025-03-26

# 使用框架的 npm 脚本
wrangler pages dev -- npm run dev

绑定资源（KV、D1、R2）

# wrangler.toml
name = "my-pages"
compatibility_date = "2025-03-26"

# 本地开发时自动创建模拟资源
[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

[[d1_databases]]
binding = "MY_DB"
database_name = "my-database"
database_id = "xxx"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

本地开发时 wrangler pages dev 会自动创建本地模拟的 KV、D1、R2 实例（数据存在 .wrangler/ 目录下）。

在 Functions 中使用绑定：

// functions/api/data.js
export async function onRequestGet(context) {
  const { env } = context

  // KV 操作
  await env.MY_KV.put("key", "value")
  const value = await env.MY_KV.get("key")

  // D1 操作
  const result = await env.MY_DB.prepare("SELECT * FROM users").all()

  return Response.json({ kv: value, db: result.results })
}

部署

# 部署静态文件目录
wrangler pages deploy ./public --project-name=my-pages

# 部署构建产物
npm run build
wrangler pages deploy ./dist --project-name=my-pages

# 直接通过 Git 集成部署（在 Cloudflare Dashboard 绑定 GitHub 仓库后自动部署）

---

Worker 绑定资源

Worker 和 Pages 都支持绑定 Cloudflare 生态资源，本地开发时自动模拟。

# wrangler.toml
name = "my-worker"
main = "src/index.js"
compatibility_date = "2025-03-26"

# KV 存储
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxx"

# D1 数据库
[[d1_databases]]
binding = "MY_DB"
database_name = "test-db"
database_id = "xxxx"

# R2 对象存储
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

# 环境变量
[vars]
API_HOST = "https://api.example.com"
DEBUG = "true"

# Secrets（敏感信息，用命令行设置，不写进 toml）
# wrangler secret put API_KEY

// src/index.js
export default {
  async fetch(request, env, ctx) {
    // env 上挂载了所有绑定的资源
    const cache = env.MY_KV          // KV
    const db = env.MY_DB             // D1
    const storage = env.MY_BUCKET    // R2
    const apiKey = env.API_KEY       // Secret
    const apiHost = env.API_HOST     // 变量

    // D1 查询
    const result = await db.prepare("SELECT 1 AS test").first()

    return Response.json({ db: result, host: apiHost })
  },
}

# 本地开发时使用 .dev.vars 文件存放敏感变量（不提交到 git）
# .dev.vars
API_KEY=sk_test_xxxx
DB_PASSWORD=local_dev_password

---

D1 本地操作

# 在本地执行 SQL（不连远程）
wrangler d1 execute MY_DB --local --command="CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"

# 执行 SQL 文件
wrangler d1 execute MY_DB --local --file=./schema.sql

# 查询数据
wrangler d1 execute MY_DB --local --command="SELECT * FROM users"

---

常用命令速查

# ========== 通用 ==========
wrangler login                    # 登录
wrangler whoami                   # 查看账号信息
wrangler dev                      # Worker 本地开发
wrangler deploy                   # 部署

# ========== Pages ==========
wrangler pages dev ./public       # Pages 本地开发
wrangler pages deploy ./dist      # Pages 部署
wrangler pages project list       # 列出项目

# ========== D1 ==========
wrangler d1 execute DB --local --command="SQL"   # 本地执行 SQL
wrangler d1 list                  # 列出所有数据库

# ========== KV ==========
wrangler kv key put --binding MY_KV "key" "value"  # 写入 KV
wrangler kv key get --binding MY_KV "key"           # 读取 KV

# ========== R2 ==========
wrangler r2 object put MY_BUCKET/file.txt ./local.txt  # 上传文件
wrangler r2 object put MY_BUCKET/file.txt --file=./local.txt
wrangler r2 object get MY_BUCKET/file.txt               # 下载文件

# ========== Secrets ==========
wrangler secret put API_KEY       # 设置 Secret
wrangler secret list              # 列出 Secrets