Cloudflare Workers 开发指南：路由、反向代理、KV 存储和 TCP Socket

Cloudflare Workers 是部署在 Cloudflare 全球边缘节点上的无服务器运行环境，写 JavaScript/TypeScript 即可，无需管理服务器。

快速开始

npm create cloudflare@latest my-worker
cd my-worker
npm run dev     # 本地调试
npm run deploy  # 部署

基础结构

export default {
  async fetch(request, env, ctx) {
    return new Response("hello world");
  },
};

路由处理

export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/api/user") {
      return Response.json({ name: "soulock" });
    }

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

获取 query 参数：

const name = url.searchParams.get("name");

获取请求体：

const data = await request.json();

反向代理

export default {
  async fetch(request) {
    const url = new URL(request.url);
    const target = "https://example.com";

    const targetUrl = new URL(url.pathname + url.search, target);

    const headers = new Headers(request.headers);
    headers.set("Host", targetUrl.host);

    const resp = await fetch(targetUrl.toString(), {
      method: request.method,
      headers,
      body: request.body,
      redirect: "follow",
    });

    return new Response(resp.body, {
      status: resp.status,
      headers: resp.headers,
    });
  },
};

流式返回（AI 接口必须用这种写法）：

// 正确：保持流式
return new Response(resp.body, resp);

// 错误：会阻塞到完整响应
const text = await resp.text();

CORS 处理

function corsHeaders() {
  return {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "*",
    "Access-Control-Allow-Headers": "*",
  };
}

export default {
  async fetch(request) {
    if (request.method === "OPTIONS") {
      return new Response(null, { headers: corsHeaders() });
    }

    const resp = await fetch("https://example.com");

    return new Response(resp.body, {
      status: resp.status,
      headers: { ...Object.fromEntries(resp.headers), ...corsHeaders() },
    });
  },
};

环境变量

# wrangler.toml
[vars]
API_KEY = "xxx"

代码里用 env.API_KEY。生产环境推荐用 secret（不写入代码）：

wrangler secret put API_KEY

KV 存储

[[kv_namespaces]]
binding = "MY_KV"
id = "xxxx"

await env.MY_KV.put("key", "value");
const value = await env.MY_KV.get("key");

D1 数据库（SQLite）

wrangler d1 create mydb

[[d1_databases]]
binding = "DB"
database_name = "mydb"
database_id = "xxxx"

const result = await env.DB.prepare("SELECT * FROM users").all();

定时任务

export default {
  async scheduled(event, env, ctx) {
    // 定时执行的逻辑
  },
};

[triggers]
crons = ["*/5 * * * *"]

TCP Socket

Workers 支持主动发起 TCP 连接（不能监听 TCP）：

import { connect } from "cloudflare:sockets";

const socket = connect({ hostname: "example.com", port: 80 });
const writer = socket.writable.getWriter();
await writer.write(new TextEncoder().encode("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n"));
writer.releaseLock();
return new Response(socket.readable);

常见用途：WebSocket → TCP 隧道，代理 Redis、PostgreSQL 等 TCP 协议。

Workers 不能替代大流量 TCP 服务（有连接数和执行时间限制），适合轻量中转。

推荐：Hono 框架

npm i hono

import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => c.text("hello"));
app.get("/user", (c) => c.json({ name: "soulock" }));

// 反向代理
app.all("*", async (c) => {
  const url = new URL(c.req.url);
  const target = "https://example.com" + url.pathname + url.search;
  const resp = await fetch(target, { method: c.req.method, headers: c.req.raw.headers, body: c.req.raw.body });
  return new Response(resp.body, resp);
});

export default app;

适合与不适合的场景

适合	不适合
API 网关 / 鉴权	大型 CPU 运算
AI 接口中转	ffmpeg / 视频编码
Webhook / Bot	Puppeteer
反向代理	本地文件读写
短链接 / 边缘缓存	高并发大流量 VPN

Workers 没有 fs、child_process、net 等 Node.js 原生模块，运行在沙盒环境中。