wrangler-coder

Wrangler 编码

Wrangler 是 Cloudflare 为 Workers、Pages、D1、R2、KV、Queues 和 AI 提供的官方 CLI。

安装

# npm
npm install -g wrangler

# pnpm
pnpm add -g wrangler

# Verify installation
wrangler --version

身份验证

# Interactive login (opens browser)
wrangler login

# Check authentication status
wrangler whoami

# Logout
wrangler logout

环境变量：

# API Token (preferred for CI/CD)
export CLOUDFLARE_API_TOKEN="your-api-token"

# Or with 1Password
CLOUDFLARE_API_TOKEN=op://Infrastructure/Cloudflare/wrangler_token

# Account ID (optional, can be in wrangler.toml)
export CLOUDFLARE_ACCOUNT_ID="your-account-id"

项目初始化

# Create new Worker project
wrangler init my-worker

# Create from template
wrangler init my-worker --template cloudflare/worker-template

# Initialize in existing directory
wrangler init

wrangler.toml 配置

基础 Worker

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"

# Account ID (can also use CLOUDFLARE_ACCOUNT_ID env var)
account_id = "your-account-id"

# Worker settings
workers_dev = true  # Enable *.workers.dev subdomain

带路由的 Worker

name = "api-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
account_id = "your-account-id"

# Custom domain routes
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" },
  { pattern = "example.com/api/*", zone_name = "example.com" }
]

多环境配置

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
account_id = "your-account-id"

# Development (default)
workers_dev = true

# Staging environment
[env.staging]
name = "my-worker-staging"
routes = [
  { pattern = "staging-api.example.com/*", zone_name = "example.com" }
]
vars = { ENVIRONMENT = "staging" }

# Production environment
[env.production]
name = "my-worker-production"
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]
vars = { ENVIRONMENT = "production" }

Cloudflare 产品

产品	资源
KV 命名空间	references/kv-namespaces.md
D1 数据库与 R2 存储	references/d1-r2.md
Queues 与 Durable Objects	references/queues-durable-objects.md
Workers AI	references/workers-ai.md
Cloudflare Pages	references/pages.md

密钥管理

# Add secret
wrangler secret put API_KEY
# (prompts for value)

# Add secret for specific environment
wrangler secret put API_KEY --env production

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete API_KEY

# Bulk secrets from .dev.vars file (local dev only)
# Create .dev.vars file:
# API_KEY=xxx
# DB_PASSWORD=yyy

export interface Env {
  API_KEY: string;
  DB_PASSWORD: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Access secrets from env
    const apiKey = env.API_KEY;
    return new Response(`Key length: ${apiKey.length}`);
  }
};

开发工作流

本地开发

# Start local dev server
wrangler dev

# With specific environment
wrangler dev --env staging

# Custom port
wrangler dev --port 8787

# Remote mode (uses Cloudflare's network)
wrangler dev --remote

# Local mode with persistent storage
wrangler dev --persist-to ./data

测试

# Run tests with vitest (recommended)
npm install -D vitest @cloudflare/vitest-pool-workers

# vitest.config.ts
# import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
# export default defineWorkersConfig({
#   test: { poolOptions: { workers: { wrangler: { configPath: './wrangler.toml' } } } }
# });

部署

# Deploy to workers.dev
wrangler deploy

# Deploy to specific environment
wrangler deploy --env production

# Dry run (show what would be deployed)
wrangler deploy --dry-run

# Deploy with custom name
wrangler deploy --name my-custom-worker

日志与调试

# Tail logs (real-time)
wrangler tail

# Tail specific environment
wrangler tail --env production

# Filter logs
wrangler tail --status error
wrangler tail --search "user-id-123"
wrangler tail --ip 1.2.3.4

# View deployment versions
wrangler versions list

# Rollback to previous version
wrangler rollback

完整 Worker 示例

请参阅 references/worker-example.md，了解一个可用于生产环境的 Worker 示例，其中包含 D1、KV、R2 绑定、多环境配置和 CORS 处理。

最佳实践

• 固定 compatibility_date - 确保不同部署之间的行为可复现
• 使用环境 - 在同一个文件中分离暂存环境和生产环境配置
• 通过 CLI 管理密钥 - 切勿提交密钥，请使用 wrangler secret put
• 本地持久化 - 使用 --persist-to 保持本地开发状态一致
• 在生产环境中跟踪日志 - 使用 wrangler tail --status error 调试问题
• 对 wrangler.toml 进行版本控制 - 跟踪配置变更
• 使用 .dev.vars 存储本地密钥 - 将其添加到 .gitignore
• 批量执行 D1 操作 - 使用 env.DB.batch() 降低延迟
• 有策略地缓存 - 使用 KV 存储频繁访问的数据
• 妥善处理错误 - 返回正确的 HTTP 状态码