cloudflare-workers（Cloudflare Workers 开发）

Cloudflare Workers

Serverless platform for building applications across Cloudflare's global network.

Quick Navigation

• Runtime & handlers → references/runtime.md
• Bindings overview → references/bindings.md
• Wrangler configuration → references/wrangler.md
• Local development → references/local-dev.md
• Static assets → references/assets.md
• Testing → references/testing.md

When to Use

• Building serverless APIs or full-stack applications
• Running edge functions with global distribution
• Connecting to Cloudflare storage (KV, R2, D1, Durable Objects)
• Running AI inference with Workers AI
• Configuring Wrangler CLI and wrangler.toml
• Setting up local development with Miniflare
• Testing Workers with Vitest

Module Worker (Recommended Syntax)

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response("Hello, World!");
  },
} satisfies ExportedHandler<Env>;

Handler Types

Bindings Overview

Access Cloudflare resources via env object.

Minimal Configuration

// wrangler.jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-03-07",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Essential Commands

# Development
npx wrangler dev              # Local dev (Miniflare)
npx wrangler dev --remote     # Remote dev (code on Cloudflare)

# Deployment
npx wrangler deploy           # Deploy to production
npx wrangler versions upload  # Upload without deploying
npx wrangler versions deploy  # Promote version

# Secrets
npx wrangler secret put KEY   # Add secret
npx wrangler secret list      # List secrets

# Types
npx wrangler types            # Generate TypeScript types

Compatibility Settings

# wrangler.toml
compatibility_date = "2025-03-07"
compatibility_flags = ["nodejs_compat"]

Key flags:

• nodejs_compat — Enable Node.js APIs
• nodejs_compat_v2 — Improved process implementation

Quick Recipes

Fetch Handler with Routing

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

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

    if (url.pathname.startsWith("/static/")) {
      return env.ASSETS.fetch(request);
    }

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

Scheduled Handler (Cron)

export default {
  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
    ctx.waitUntil(doBackgroundWork(env));
  },
};

# wrangler.toml
[triggers]
crons = ["0 * * * *"]  # Every hour

Queue Consumer

export default {
  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
    for (const message of batch.messages) {
      console.log(message.body);
      message.ack();
    }
  },
};

Critical Prohibitions

• Do NOT store secrets in wrangler.toml — use wrangler secret put
• Do NOT use remote: true for Durable Objects or Workflows — unsupported
• Do NOT expect Workers AI to work locally — always requires remote connection
• Do NOT omit compatibility_date — defaults to oldest date (2021-11-02)
• Do NOT use Service Worker syntax for new projects — use ES Modules
• Do NOT mix Service Worker and Module syntax in same project

Common Gotchas

Links

• Documentation
• Changelog

Related Skills

• cloudflare-pages — Full-stack hosting with Git deployment
• cloudflare-d1 — D1 database operations
• cloudflare-r2 — R2 object storage
• cloudflare-kv — KV namespace operations
• cloudflare-durable-objects — Stateful coordination