Cloudflare Workers 入门：把你的代码跑在离用户最近的地方

如果你写过后端接口，大概率经历过这种流程：

买一台服务器（或者开一个云函数），把代码部署上去，然后所有用户的请求都打到同一个地方。用户在北京，服务器在美西——那就忍着 200ms 的延迟吧。

Cloudflare Workers 做的事情很简单：让你的代码跑在全球 300+ 个边缘节点上，用户请求到哪个节点近，就在哪个节点执行。

不是 CDN 缓存静态文件那种"近"，是你的业务逻辑真的在边缘跑。

它到底是什么？

Cloudflare Workers 是一个 Serverless 运行时，但它和 AWS Lambda、Vercel Functions 这类产品有一个本质区别：

特性	传统 Serverless（Lambda 等）	Cloudflare Workers
运行位置	固定区域（如 us-east-1）	全球边缘节点
冷启动	几百毫秒到几秒	几乎没有（V8 Isolate）
运行时	Node.js / Python / Go 等	V8 Isolate（类浏览器环境）
执行时长限制	通常 15 分钟	免费版 10ms CPU / 付费版 30s CPU
适合场景	重计算、长任务	轻量请求处理、API 网关、边缘逻辑

关键词是 V8 Isolate。Workers 不启动完整的 Node.js 进程，而是在 V8 引擎里创建一个轻量级隔离环境。这就是它冷启动几乎为零的原因——没有进程启动开销，只有 Isolate 的创建。

代价是：你拿不到完整的 Node.js API。fs、child_process 这些不存在。你能用的是 Web 标准 API：fetch、Request、Response、URL、crypto、TextEncoder 等。

如果你写过 Service Worker 或者 Deno，这个心智模型会很熟悉。

5 分钟跑起来第一个 Worker

前置条件

一个 Cloudflare 账号（免费即可）
Node.js 16+ 或 Bun

1. 创建项目

bash

bun create cloudflare@latest my-first-worker

交互式引导会问你几个问题，选 "Hello World" Worker 模板就行。

创建完成后进入项目目录：

bash

cd my-first-worker

你会看到这样的结构：

plaintext

my-first-worker/
├── src/
│   └── index.ts        # 你的 Worker 代码
├── wrangler.jsonc       # 配置文件
├── package.json
└── tsconfig.json

2. 看一眼核心代码

打开 src/index.ts：

typescript

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

就这么多。一个 Worker 本质上就是一个导出了 fetch 方法的模块。每次有 HTTP 请求进来，这个方法就会被调用。

三个参数：

request：标准的 Web Request 对象，包含 URL、method、headers、body 等
env：环境变量和绑定资源（KV、D1、R2 等，后面会讲）
ctx：执行上下文，主要用 ctx.waitUntil() 做异步后台任务

3. 本地开发

bash

bun run dev

这会启动 wrangler dev，在本地起一个模拟 Workers 运行时的开发服务器。默认监听 http://localhost:8787。

打开浏览器访问，你会看到 "Hello World!"。

4. 部署到线上

bash

bun run deploy

第一次会要求你登录 Cloudflare 账号。部署完成后会给你一个 *.workers.dev 的域名，全球可访问。

就这样，你的代码已经跑在全球 300+ 个节点上了。

写一个有点用的东西

"Hello World" 看完了，来写个实际点的：一个简单的 API 路由。

typescript

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<Response> {
    const url = new URL(request.url)
 
    if (url.pathname === '/api/time') {
      return Response.json({
        utc: new Date().toISOString(),
        timestamp: Date.now(),
      })
    }
 
    if (url.pathname === '/api/geo') {
      // Cloudflare 会自动注入请求的地理信息
      const cf = (request as any).cf
      return Response.json({
        country: cf?.country,
        city: cf?.city,
        timezone: cf?.timezone,
        colo: cf?.colo, // 处理这个请求的数据中心代码
      })
    }
 
    if (url.pathname === '/api/echo' && request.method === 'POST') {
      const body = await request.text()
      return Response.json({
        received: body,
        headers: Object.fromEntries(request.headers),
      })
    }
 
    return new Response('Not Found', { status: 404 })
  },
}

几个值得注意的点：

request.cf 是 Cloudflare 独有的扩展，包含请求的地理位置、ASN、TLS 版本等信息，不需要额外调用 IP 库
Response.json() 是 Web 标准 API，自动设置 Content-Type: application/json
路由逻辑就是普通的 if/else——项目小的时候这样写完全够用，大了再上框架

环境变量和 Secrets

Workers 的环境变量通过 wrangler.jsonc 配置：

jsonc

{
  "name": "my-first-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-28",
  "vars": {
    "API_VERSION": "v1",
  },
}

在代码里通过 env 参数访问：

typescript

async fetch(request: Request, env: Env) {
  return new Response(`API Version: ${env.API_VERSION}`);
}

敏感信息（API Key、Token 等）不要写在配置文件里，用 secret：

bash

bunx wrangler secret put MY_API_KEY

它会提示你输入值，加密存储在 Cloudflare 侧。代码里访问方式和普通变量一样：env.MY_API_KEY。

Workers 生态里你需要知道的几个存储方案

Workers 本身是无状态的。如果你需要存数据，Cloudflare 提供了几个配套服务：

KV（Key-Value）

全球分布式键值存储，最终一致性。适合读多写少的场景，比如配置、缓存、特征开关。

typescript

// 写入
await env.MY_KV.put('user:123', JSON.stringify({ name: 'Chiway' }))
 
// 读取
const data = await env.MY_KV.get('user:123', 'json')

D1（SQLite）

边缘 SQLite 数据库。适合需要关系查询但数据量不大的场景。

typescript

const result = await env.DB.prepare('SELECT * FROM posts WHERE slug = ?')
  .bind('hello-world')
  .first()

R2（对象存储）

S3 兼容的对象存储，零出口费用。适合存文件、图片、备份。

typescript

// 上传
await env.BUCKET.put('images/photo.jpg', imageBuffer)
 
// 下载
const object = await env.BUCKET.get('images/photo.jpg')

Durable Objects

有状态的边缘计算单元。适合需要强一致性的场景，比如实时协作、计数器、WebSocket 连接管理。

这个概念稍微复杂一些，入门阶段可以先跳过。

几个实际开发中的注意事项

1. CPU 时间 ≠ 墙钟时间

Workers 的执行时长限制是 CPU 时间，不是墙钟时间。也就是说，await fetch(...) 等待外部响应的时间不算在内。免费版 10ms CPU 时间听起来很短，但对于大多数请求处理逻辑来说绑绑有余。

2. 不要在 Worker 里做重计算

加密哈希、图片处理、大 JSON 解析——这些 CPU 密集型操作会很快吃完你的配额。如果确实需要，考虑用 Workers 做调度，把重活交给其他服务。

3. `ctx.waitUntil()` 是你的好朋友

如果你需要在返回响应之后做一些异步操作（比如写日志、更新缓存），用 ctx.waitUntil()：

typescript

async fetch(request: Request, env: Env, ctx: ExecutionContext) {
  // 先返回响应
  const response = new Response('OK');
 
  // 后台异步执行，不阻塞响应
  ctx.waitUntil(
    env.MY_KV.put('last-visit', new Date().toISOString())
  );
 
  return response;
}

4. 本地开发和线上行为可能有差异

wrangler dev 尽量模拟了 Workers 运行时，但某些边缘情况（比如 request.cf 的字段、KV 的一致性行为）在本地和线上可能不完全一致。关键逻辑建议部署到 staging 环境验证。

什么时候该用、什么时候不该用

适合用 Workers 的场景：

API 网关 / 请求路由
A/B 测试、特征开关
认证鉴权（JWT 验证、OAuth 中间件）
请求/响应改写（加 header、重定向、内容替换）
轻量 API（表单处理、Webhook 接收）
边缘缓存策略

不太适合的场景：

长时间运行的任务（视频转码、大批量数据处理）
需要完整 Node.js 生态的项目（大量 npm 包依赖 Node API）
需要持久化 WebSocket 连接但不想用 Durable Objects 的场景

总结

Cloudflare Workers 的核心价值就一句话：把轻量逻辑推到离用户最近的地方执行。

它不是万能的，CPU 时间有限、运行时 API 受限、调试体验还有提升空间。但在它擅长的领域——请求处理、边缘逻辑、API 网关——它的延迟优势和开发体验确实很难被替代。

如果你之前只用过传统 Serverless，建议花半小时跑一遍上面的流程。体验过"部署即全球可用"之后，你对后端架构的思考方式可能会有一些变化。

免费版每天 10 万次请求，个人项目和小型服务完全够用。先跑起来，遇到边界再说。

如果你写过后端接口，大概率经历过这种流程：

Cloudflare Workers 做的事情很简单：让你的代码跑在全球 300+ 个边缘节点上，用户请求到哪个节点近，就在哪个节点执行。

不是 CDN 缓存静态文件那种"近"，是你的业务逻辑真的在边缘跑。

它到底是什么？

Cloudflare Workers 是一个 Serverless 运行时，但它和 AWS Lambda、Vercel Functions 这类产品有一个本质区别：

特性	传统 Serverless（Lambda 等）	Cloudflare Workers
运行位置	固定区域（如 us-east-1）	全球边缘节点
冷启动	几百毫秒到几秒	几乎没有（V8 Isolate）
运行时	Node.js / Python / Go 等	V8 Isolate（类浏览器环境）
执行时长限制	通常 15 分钟	免费版 10ms CPU / 付费版 30s CPU
适合场景	重计算、长任务	轻量请求处理、API 网关、边缘逻辑

代价是：你拿不到完整的 Node.js API。fs、child_process 这些不存在。你能用的是 Web 标准 API：fetch、Request、Response、URL、crypto、TextEncoder 等。

如果你写过 Service Worker 或者 Deno，这个心智模型会很熟悉。

5 分钟跑起来第一个 Worker

前置条件

一个 Cloudflare 账号（免费即可）
Node.js 16+ 或 Bun

1. 创建项目

bash

bun create cloudflare@latest my-first-worker

交互式引导会问你几个问题，选 "Hello World" Worker 模板就行。

创建完成后进入项目目录：

bash

cd my-first-worker

你会看到这样的结构：

plaintext

my-first-worker/
├── src/
│   └── index.ts        # 你的 Worker 代码
├── wrangler.jsonc       # 配置文件
├── package.json
└── tsconfig.json

2. 看一眼核心代码

打开 src/index.ts：

typescript

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

就这么多。一个 Worker 本质上就是一个导出了 fetch 方法的模块。每次有 HTTP 请求进来，这个方法就会被调用。

三个参数：

request：标准的 Web Request 对象，包含 URL、method、headers、body 等
env：环境变量和绑定资源（KV、D1、R2 等，后面会讲）
ctx：执行上下文，主要用 ctx.waitUntil() 做异步后台任务

3. 本地开发

bash

bun run dev

这会启动 wrangler dev，在本地起一个模拟 Workers 运行时的开发服务器。默认监听 http://localhost:8787。

打开浏览器访问，你会看到 "Hello World!"。

4. 部署到线上

bash

bun run deploy

第一次会要求你登录 Cloudflare 账号。部署完成后会给你一个 *.workers.dev 的域名，全球可访问。

就这样，你的代码已经跑在全球 300+ 个节点上了。

写一个有点用的东西

"Hello World" 看完了，来写个实际点的：一个简单的 API 路由。

typescript

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<Response> {
    const url = new URL(request.url)
 
    if (url.pathname === '/api/time') {
      return Response.json({
        utc: new Date().toISOString(),
        timestamp: Date.now(),
      })
    }
 
    if (url.pathname === '/api/geo') {
      // Cloudflare 会自动注入请求的地理信息
      const cf = (request as any).cf
      return Response.json({
        country: cf?.country,
        city: cf?.city,
        timezone: cf?.timezone,
        colo: cf?.colo, // 处理这个请求的数据中心代码
      })
    }
 
    if (url.pathname === '/api/echo' && request.method === 'POST') {
      const body = await request.text()
      return Response.json({
        received: body,
        headers: Object.fromEntries(request.headers),
      })
    }
 
    return new Response('Not Found', { status: 404 })
  },
}

几个值得注意的点：

request.cf 是 Cloudflare 独有的扩展，包含请求的地理位置、ASN、TLS 版本等信息，不需要额外调用 IP 库
Response.json() 是 Web 标准 API，自动设置 Content-Type: application/json
路由逻辑就是普通的 if/else——项目小的时候这样写完全够用，大了再上框架

环境变量和 Secrets

Workers 的环境变量通过 wrangler.jsonc 配置：

jsonc

{
  "name": "my-first-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-28",
  "vars": {
    "API_VERSION": "v1",
  },
}

在代码里通过 env 参数访问：

typescript

async fetch(request: Request, env: Env) {
  return new Response(`API Version: ${env.API_VERSION}`);
}

敏感信息（API Key、Token 等）不要写在配置文件里，用 secret：

bash

bunx wrangler secret put MY_API_KEY

它会提示你输入值，加密存储在 Cloudflare 侧。代码里访问方式和普通变量一样：env.MY_API_KEY。

Workers 生态里你需要知道的几个存储方案

Workers 本身是无状态的。如果你需要存数据，Cloudflare 提供了几个配套服务：

KV（Key-Value）

全球分布式键值存储，最终一致性。适合读多写少的场景，比如配置、缓存、特征开关。

typescript

// 写入
await env.MY_KV.put('user:123', JSON.stringify({ name: 'Chiway' }))
 
// 读取
const data = await env.MY_KV.get('user:123', 'json')

D1（SQLite）

边缘 SQLite 数据库。适合需要关系查询但数据量不大的场景。

typescript

const result = await env.DB.prepare('SELECT * FROM posts WHERE slug = ?')
  .bind('hello-world')
  .first()

R2（对象存储）

S3 兼容的对象存储，零出口费用。适合存文件、图片、备份。

typescript

// 上传
await env.BUCKET.put('images/photo.jpg', imageBuffer)
 
// 下载
const object = await env.BUCKET.get('images/photo.jpg')

Durable Objects

有状态的边缘计算单元。适合需要强一致性的场景，比如实时协作、计数器、WebSocket 连接管理。

这个概念稍微复杂一些，入门阶段可以先跳过。

几个实际开发中的注意事项

1. CPU 时间 ≠ 墙钟时间

2. 不要在 Worker 里做重计算

加密哈希、图片处理、大 JSON 解析——这些 CPU 密集型操作会很快吃完你的配额。如果确实需要，考虑用 Workers 做调度，把重活交给其他服务。

3. `ctx.waitUntil()` 是你的好朋友

如果你需要在返回响应之后做一些异步操作（比如写日志、更新缓存），用 ctx.waitUntil()：

typescript

async fetch(request: Request, env: Env, ctx: ExecutionContext) {
  // 先返回响应
  const response = new Response('OK');
 
  // 后台异步执行，不阻塞响应
  ctx.waitUntil(
    env.MY_KV.put('last-visit', new Date().toISOString())
  );
 
  return response;
}

4. 本地开发和线上行为可能有差异

什么时候该用、什么时候不该用

适合用 Workers 的场景：

API 网关 / 请求路由
A/B 测试、特征开关
认证鉴权（JWT 验证、OAuth 中间件）
请求/响应改写（加 header、重定向、内容替换）
轻量 API（表单处理、Webhook 接收）
边缘缓存策略

不太适合的场景：

长时间运行的任务（视频转码、大批量数据处理）
需要完整 Node.js 生态的项目（大量 npm 包依赖 Node API）
需要持久化 WebSocket 连接但不想用 Durable Objects 的场景

总结

Cloudflare Workers 的核心价值就一句话：把轻量逻辑推到离用户最近的地方执行。

如果你之前只用过传统 Serverless，建议花半小时跑一遍上面的流程。体验过"部署即全球可用"之后，你对后端架构的思考方式可能会有一些变化。

免费版每天 10 万次请求，个人项目和小型服务完全够用。先跑起来，遇到边界再说。

它到底是什么？

5 分钟跑起来第一个 Worker

前置条件

1. 创建项目

2. 看一眼核心代码

3. 本地开发

4. 部署到线上

写一个有点用的东西

环境变量和 Secrets

Workers 生态里你需要知道的几个存储方案

KV（Key-Value）

D1（SQLite）

R2（对象存储）

Durable Objects

几个实际开发中的注意事项

1. CPU 时间 ≠ 墙钟时间

2. 不要在 Worker 里做重计算

3. ctx.waitUntil() 是你的好朋友

4. 本地开发和线上行为可能有差异

什么时候该用、什么时候不该用

总结

它到底是什么？

5 分钟跑起来第一个 Worker

前置条件

1. 创建项目

2. 看一眼核心代码

3. 本地开发

4. 部署到线上

写一个有点用的东西

环境变量和 Secrets

Workers 生态里你需要知道的几个存储方案

KV（Key-Value）

D1（SQLite）

R2（对象存储）

Durable Objects

几个实际开发中的注意事项

1. CPU 时间 ≠ 墙钟时间

2. 不要在 Worker 里做重计算

3. ctx.waitUntil() 是你的好朋友

4. 本地开发和线上行为可能有差异

什么时候该用、什么时候不该用

总结

3. `ctx.waitUntil()` 是你的好朋友

3. `ctx.waitUntil()` 是你的好朋友