⚡

CloudflareWorkers开发体验 workers-dev-experience

这个技能涉及使用 Cloudflare Workers 进行 Serverless 本地开发，包括配置 Wrangler、Miniflare 工具，设置热重载和调试，用于项目搭建、错误处理和优化开发流程。关键词：Cloudflare Workers, Wrangler, Miniflare, 本地开发, Serverless, 热重载, 调试, 配置管理

Serverless 0 次安装 0 次浏览 更新于 3/8/2026

name: workers-dev-experience description: Cloudflare Workers 本地开发，使用 Wrangler、Miniflare、热重载、调试。用于项目设置、wrangler.jsonc 配置，或遇到本地开发、HMR、绑定模拟错误。

Cloudflare Workers 开发体验

使用 Wrangler、Miniflare 和现代工具进行本地开发设置。

快速开始

# 创建新项目
bunx create-cloudflare@latest my-worker

# 或从零开始
mkdir my-worker && cd my-worker
bun init -y
bun add -d wrangler @cloudflare/workers-types

# 启动本地开发
bunx wrangler dev

必要的 wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",

  // 开发设置
  "dev": {
    "port": 8787,
    "local_protocol": "http"
  },

  // 环境变量（非机密）
  "vars": {
    "ENVIRONMENT": "development"
  },

  // 绑定
  "kv_namespaces": [
    { "binding": "KV", "id": "abc123", "preview_id": "def456" }
  ],

  "d1_databases": [
    { "binding": "DB", "database_id": "xyz789", "database_name": "my-db" }
  ],

  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ]
}

关键规则

  1. 始终使用 wrangler dev 进行本地测试 - 准确模拟 Cloudflare 运行时
  2. 设置 compatibility_date - 控制运行时行为，每季度更新
  3. 为本地开发使用预览 ID - 与生产绑定分离
  4. 正确配置 TypeScript - 使用 @cloudflare/workers-types
  5. 启用源映射 - 开发中更好的错误堆栈

预防的六大错误

错误 症状 预防措施
模块未找到 部署时导入错误 在 tsconfig 中设置 "moduleResolution": "bundler"
绑定未定义 本地 env.KV is undefined 在 KV 命名空间配置中添加 preview_id
HMR 不工作 更改未反映 检查端口冲突，使用 --local 标志
D1 架构不匹配 本地查询失败 在本地数据库上运行迁移
类型错误 缺少绑定类型 使用 wrangler types 生成类型
CORS 问题 浏览器阻止请求 在开发处理程序中添加 CORS 头部

本地开发工作流

# 启动开发服务器（推荐）
bunx wrangler dev

# 使用实时重载
bunx wrangler dev --live-reload

# 远程模式（使用实际的 Cloudflare 服务）
bunx wrangler dev --remote

# 指定环境
bunx wrangler dev --env staging

# 自定义端口
bunx wrangler dev --port 3000

TypeScript 配置

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "types": ["@cloudflare/workers-types"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Package.json 脚本

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "deploy:production": "wrangler deploy --env production",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "type-check": "tsc --noEmit",
    "lint": "eslint src/",
    "types": "wrangler types",
    "tail": "wrangler tail",
    "db:migrate": "wrangler d1 migrations apply DB",
    "db:studio": "wrangler d1 execute DB --local --command 'SELECT 1'"
  }
}

调试

控制台日志

// 仅开发环境日志
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (env.ENVIRONMENT === 'development') {
      console.log('请求:', request.method, request.url);
      console.log('头部:', Object.fromEntries(request.headers));
    }

    // 处理逻辑...
  }
};

使用 wrangler tail

# 从部署的 worker 获取实时日志
wrangler tail

# 按状态过滤
wrangler tail --status error

# 按方法过滤
wrangler tail --method POST

# JSON 格式用于解析
wrangler tail --format json

VS Code 调试

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Wrangler Dev",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "bunx",
      "runtimeArgs": ["wrangler", "dev", "--inspector-port", "9229"],
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true
    }
  ]
}

何时加载参考

根据任务加载特定参考：

  • 设置项目？ → 加载 references/local-development.md 获取完整设置指南
  • 配置 wrangler？ → 加载 references/wrangler-config.md 获取所有配置选项
  • 调试问题？ → 加载 references/debugging-tools.md 获取调试技巧

模板

模板 目的 使用时机
templates/wrangler-config.jsonc 完整的 wrangler 配置 启动新项目
templates/dev-script.ts 开发工具 添加开发助手

脚本

脚本 目的 命令
scripts/dev-setup.sh 初始化开发环境 ./dev-setup.sh

资源