{
  "id": "codex-rules-for-cloudflare-workers",
  "type": "rules",
  "category": "rules",
  "locale": "zh",
  "url": "/zh/rules/codex-rules-for-cloudflare-workers",
  "title": "Cloudflare Workers 的 Codex 规则",
  "description": "针对 Cloudflare Workers 项目的 Codex 规则，防止使用 Node.js API，强制执行绑定模式，并将代理限制在 Workers 运行时约束内。",
  "tools": [
    "Codex",
    "Cursor",
    "Claude Code"
  ],
  "stack": [
    "Cloudflare",
    "TypeScript"
  ],
  "tags": [
    "cloudflare",
    "typescript",
    "conventions",
    "deploy"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "将此内容添加为 `AGENTS.md` 或 Codex 系统提示片段。Cloudflare Workers 运行在 V8 隔离运行时上——而不是 Node.js——因此代理需要明确的护栏，以避免生成在本地开发中静默失败但在部署时崩溃的代码。\n\n## 为什么这些规则\n\n- **不要使用 `process.env`** 是 AI 代理最常犯的 Cloudflare Workers 错误。在 Node.js 和 Next.js 代码库上训练的代理默认会使用 `process.env.MY_SECRET`。在 Workers 上，这在运行时是 `undefined`——绑定通过 `env` 参数传入，而不是进程环境。\n- **使用 `ctx.waitUntil()` 处理副作用** 可以防止一类微妙的数丢失错误。Workers 一旦返回 `Response` 就会终止隔离。任何在响应发送后执行的 `await` 如果没有 `waitUntil` 包裹，都会被静默丢弃，导致分析事件丢失、日志写入失败或数据库更新不完整。\n\n## 适用场景\n\n- Cloudflare Workers API、边缘中间件、基于 Hono 的 Workers 路由器、带有 D1/KV/R2 绑定的 Workers。\n\n## 不适用场景\n\n- Cloudflare Pages Functions（运行时类似，但使用不同的基于文件的路由约定）或通过 `nodejs_compat` 标志启用完整 Node.js API 并故意部署到 Node.js 的项目。"
}