cloudflare-workers-dev-experience

用途

本技能用于 Cloudflare Workers 的本地开发，基于 Wrangler、Miniflare 与现代工具链，帮助完成项目搭建、配置与调试。适用于项目初始化、wrangler.jsonc 配置，或遇到本地开发相关问题时使用。

主要能力

项目脚手架：使用 bunx create-cloudflare@latest my-worker 创建新项目，或从零开始初始化。
本地开发：通过 wrangler dev 在本地模拟 Cloudflare 运行时，支持热重载、远程模式、指定环境与自定义端口。
配置管理：提供 wrangler.jsonc 配置示例，涵盖 dev 设置、环境变量、KV、D1、R2 等绑定。
TypeScript 支持：提供 tsconfig.json 配置，使用 @cloudflare/workers-types。
脚本与调试：提供 package.json 脚本、控制台日志、wrangler tail 实时日志与 VS Code 调试配置。
错误预防：列出常见错误及其症状与预防方法。

使用方式

快速开始

# Create new project
bunx create-cloudflare@latest my-worker

# Or from scratch
mkdir my-worker && cd my-worker
bun init -y
bun add -d wrangler @cloudflare/workers-types

# Start local development
bunx wrangler dev

安全安装

脚手架工具如 bunx create-cloudflare 会下载并执行远程代码。运行前应遵循供应链安全最佳实践：

阻止安装后脚本：npm config set ignore-scripts true（Bun 默认禁用）。
冷却期：等待 7 天，让新版本经过社区审查。
安装前审计：运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查包。

完整安全配置（包括 Socket CLI 集成、冷却设置、锁文件验证与 CI 强制执行）可加载 dependency-upgrade 技能。

核心 wrangler.jsonc 配置

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

  // Development settings
  "dev": {
    "port": 8787,
    "local_protocol": "http"
  },

  // Environment variables (non-secret)
  "vars": {
    "ENVIRONMENT": "development"
  },

  // Bindings
  "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" }
  ]
}

关键规则

始终使用 wrangler dev 进行本地测试，以准确模拟 Cloudflare 运行时。
设置 compatibility_date，控制运行时行为，每季度更新。
本地开发使用 preview ID，与生产绑定分离。
正确配置 TypeScript，使用 @cloudflare/workers-types。
启用 source maps，获得更好的错误堆栈。

预防的 6 大错误

错误	症状	预防
Module not found	部署时导入错误	在 tsconfig 中设置 `"moduleResolution": "bundler"`
Binding undefined	本地 `env.KV` 未定义	为 KV 命名空间配置添加 `preview_id`
HMR not working	更改未生效	检查端口冲突，使用 `--local` 标志
D1 schema mismatch	本地查询失败	在本地数据库运行迁移
Type errors	缺少绑定类型	使用 `wrangler types` 生成类型
CORS issues	浏览器阻止请求	在开发处理器中添加 CORS 头

本地开发工作流

# Start dev server (recommended)
bunx wrangler dev

# With live reload
bunx wrangler dev --live-reload

# Remote mode (use actual Cloudflare services)
bunx wrangler dev --remote

# Specify environment
bunx wrangler dev --env staging

# Custom port
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'"
  }
}

调试

控制台日志：

// Development-only logging
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (env.ENVIRONMENT === 'development') {
      console.log('Request:', request.method, request.url);
      console.log('Headers:', Object.fromEntries(request.headers));
    }

    // Handler logic...
  }
};

使用 wrangler tail：

# Real-time logs from deployed worker
wrangler tail

# Filter by status
wrangler tail --status error

# Filter by method
wrangler tail --method POST

# JSON format for parsing
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

适用场景

新建 Cloudflare Workers 项目并完成本地开发环境搭建。
配置 wrangler.jsonc，包括绑定、环境变量与开发设置。
排查本地开发中的模块解析、绑定未定义、热重载、D1 迁移、类型与 CORS 等问题。
使用日志、wrangler tail 与 VS Code 进行调试。

限制

资料未提供该技能的具体收费、价格、平台支持范围或效果数据，暂未提供。