Cloudflare Workers 入门：从 hello world 到 KV / D1

Cloudflare Workers 本质上是”边缘 JS/TS 函数”——写一段代码，部署到全球 300 多个节点，用户就近访问。适合做 API 代理、Webhook、AI 接口中转、鉴权网关，比自建 Nginx 或买 VPS 省事。

项目起步

一个命令拉起脚手架：

npm create cloudflare@latest my-worker
cd my-worker
npm run dev        # 本地起 wrangler dev
npm run deploy     # 部署到生产

第一次部署会让你登录：

npx wrangler login

最小骨架

新版模块化写法：

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

访问 https://<name>.<account>.workers.dev 就能看到。

路由分发

原生没有路由框架，URL 手动分：

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

    if (url.pathname === "/api/user") {
      return Response.json({ name: "alice", age: 18 });
    }
    if (url.pathname === "/health") {
      return new Response("ok");
    }
    return new Response("Not Found", { status: 404 });
  },
};

要更完善的路由体验就上 Hono：

import { Hono } from "hono";
const app = new Hono();
app.get("/api/user", (c) => c.json({ name: "alice" }));
export default app;

读取请求

// query string
const url = new URL(request.url);
const name = url.searchParams.get("name");

// JSON body
const data = await request.json();

// 表单
const form = await request.formData();

转发外部 API（最常见用法）

export default {
  async fetch(request, env) {
    const resp = await fetch("https://api.openai.com/v1/models", {
      headers: { Authorization: `Bearer ${env.OPENAI_API_KEY}` },
    });
    return new Response(resp.body, resp);
  },
};

常见用途：藏 API Key、破跨域、加限流、加缓存、AI 接口中转。Key 千万别写死在代码里，走 wrangler secret。

KV：类 Redis 键值

wrangler.toml：

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

代码：

await env.MY_KV.put("username", "alice");
const v = await env.MY_KV.get("username");
await env.MY_KV.delete("username");

KV 是最终一致（全球复制有几秒延迟），做缓存 / 配置 / session 都很合适。

D1：SQLite

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

用法：

const rows = await env.DB
  .prepare("SELECT * FROM users WHERE id = ?")
  .bind(userId)
  .all();

参数化查询是标配，别拼字符串——同样有 SQL 注入。

环境变量 vs Secret

普通变量写 wrangler.toml：

[vars]
APP_NAME = "my-app"

敏感 key 用 secret，不进代码库：

npx wrangler secret put OPENAI_API_KEY

两种都通过 env.XXX 访问。

免费额度和局限

• 免费 10 万次请求/天，付费 10 美元/月起
• 单请求 CPU 时间限制（免费 10ms，付费 50ms+，最高 5 分钟）
• 不能开 socket、不能持久保存本地文件
• Node.js 内置模块要靠 nodejs_compat 兼容标志

一句话总结

Workers = 全球边缘 JavaScript。npm create cloudflare@latest 起步，fetch 转发是 90% 用例，配上 KV/D1 就能扛住一个中等 API 项目。