部署到 Cloudflare Workers

先明确 Bun 的角色

部署到 Workers 后，代码由 Cloudflare 的 workerd 执行，不是 Bun。Bun 在这里承担：包管理（bun install）、本地工具执行（bunx wrangler）、测试（bun test 跑纯逻辑）。把这条边界写进 Agent 规则，否则它会在线上代码里使用 Bun.* API。

1. 创建项目

bun create cloudflare@latest my-worker
cd my-worker
bun install

2. 配置

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-02",
  "compatibility_flags": ["nodejs_compat"]
}

nodejs_compat 让 workerd 提供一部分 Node API 兼容；它是子集，不等于完整 Node。只用 Web 标准 API 的代码可以不加这个 flag。

export default {
  async fetch(request: Request): Promise<Response> {
    return Response.json({ ok: true, runtime: 'workerd' });
  },
};

3. 本地验证与发布

bunx wrangler dev          # 本地由 workerd 执行，接近线上行为
bunx wrangler secret put API_KEY   # 密钥不进源码与 wrangler 配置
bunx wrangler deploy

wrangler dev 已经在 workerd 里跑代码，所以“本地能跑”在这里是有意义的信号——但 KV、D1、Queues 等绑定仍要按 Cloudflare 文档单独配置和演练。

边界

• 代码里不出现 Bun.serve、Bun.file、bun:sqlite 等 Bun 专有 API；共享包用 Web 标准（fetch、Request/Response、Web Crypto）。
• nodejs_compat 覆盖不全；依赖 Node 特定行为的包需要在 wrangler dev 下实测。
• CPU 时间、内存和子请求数受 Workers 限额约束；AI 长流式响应优先用 ReadableStream 并在目标套餐上压测。
• bun test 适合测纯逻辑；绑定相关行为用 Workers 官方测试工具（如 vitest-pool-workers）在 workerd 里测。

验收

1. wrangler dev 与已部署 Worker 行为一致；
2. 没有 Bun.* 引用进入部署产物；
3. 密钥全部经 wrangler secret 注入；
4. 流式响应与最长执行时间在目标套餐实测通过。

官方参考：Cloudflare Workers、Wrangler 配置、Workers Node.js 兼容。