workers-dev-experience

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Workers Developer Experience

Cloudflare Workers 开发者体验

Local development setup with Wrangler, Miniflare, and modern tooling.

使用Wrangler、Miniflare及现代工具搭建本地开发环境。

Quick Start

快速开始

bash

undefined

bash

undefined

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

undefined

bunx wrangler dev

undefined

Essential wrangler.jsonc

必备的 wrangler.jsonc 配置

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

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

Critical Rules

关键规则

Always use
wrangler dev
for local testing - Simulates Cloudflare runtime accurately
Set
compatibility_date
- Controls runtime behavior, update quarterly
Use preview IDs for local dev - Separate from production bindings
Configure TypeScript properly - Use
```
@cloudflare/workers-types
```
Enable source maps - Better error stacks in development

始终使用
wrangler dev
进行本地测试 - 精准模拟Cloudflare运行时环境
设置
compatibility_date
- 控制运行时行为，建议每季度更新一次
本地开发使用预览ID - 与生产环境绑定分离
正确配置TypeScript - 使用
```
@cloudflare/workers-types
```
启用源映射 - 提升开发阶段的错误栈可读性

Top 6 Errors Prevented

可避免的6大常见错误

Error	Symptom	Prevention
Module not found	Import errors on deploy	Set `"moduleResolution": "bundler"` in tsconfig
Binding undefined	`env.KV is undefined` locally	Add `preview_id` to KV namespace config
HMR not working	Changes not reflecting	Check port conflicts, use `--local` flag
D1 schema mismatch	Queries fail locally	Run migrations on local DB
Type errors	Missing binding types	Generate types with `wrangler types`
CORS issues	Browser blocking requests	Add CORS headers in dev handler

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

Local Development Workflow

本地开发工作流

bash

undefined

bash

undefined

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

undefined

bunx wrangler dev --port 3000

undefined

TypeScript Configuration

TypeScript 配置

tsconfig.json:

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

tsconfig.json:

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

Package.json 脚本

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'"
  }
}

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'"
  }
}

Debugging

调试

Console Logging

控制台日志

typescript

// 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...
  }
};

typescript

// 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...
  }
};

Using wrangler tail

使用wrangler tail

bash

undefined

bash

undefined

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

undefined

wrangler tail --format json

undefined

VS Code Debugging

VS Code 调试

.vscode/launch.json:

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
    }
  ]
}

.vscode/launch.json:

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
    }
  ]
}

When to Load References

参考文档加载建议

Load specific references based on the task:

Setting up project? → Load
```
references/local-development.md
```
for complete setup guide
Configuring wrangler? → Load
```
references/wrangler-config.md
```
for all configuration options
Debugging issues? → Load
```
references/debugging-tools.md
```
for debugging techniques

根据任务类型加载特定参考文档：

搭建项目？ → 加载
```
references/local-development.md
```
获取完整搭建指南
配置Wrangler？ → 加载
```
references/wrangler-config.md
```
查看所有配置选项
调试问题？ → 加载
```
references/debugging-tools.md
```
学习调试技巧

Templates

模板

Template	Purpose	Use When
`templates/wrangler-config.jsonc`	Complete wrangler config	Starting new project
`templates/dev-script.ts`	Development utilities	Adding dev helpers

模板	用途	使用场景
`templates/wrangler-config.jsonc`	完整的Wrangler配置文件	启动新项目时
`templates/dev-script.ts`	开发工具集	添加开发辅助功能时

Scripts

脚本

Script	Purpose	Command
`scripts/dev-setup.sh`	Initialize dev environment	`./dev-setup.sh`

脚本	用途	命令
`scripts/dev-setup.sh`	初始化开发环境	`./dev-setup.sh`

Resources

资源

Wrangler CLI: https://developers.cloudflare.com/workers/wrangler/
Configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
Local Development: https://developers.cloudflare.com/workers/testing/local-development/

Wrangler CLI: https://developers.cloudflare.com/workers/wrangler/
Configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
Local Development: https://developers.cloudflare.com/workers/testing/local-development/