# Cloudflare Workers 的 Codex 规则

> 针对 Cloudflare Workers 项目的 Codex 规则，防止使用 Node.js API，强制执行绑定模式，并将代理限制在 Workers 运行时约束内。

**Type:** Rule  
**Tools:** Codex, Cursor, Claude Code  
**Stack:** Cloudflare, TypeScript  
**Updated:** 2026-06-08

---

将此内容添加为 `AGENTS.md` 或 Codex 系统提示片段。Cloudflare Workers 运行在 V8 隔离运行时上——而不是 Node.js——因此代理需要明确的护栏，以避免生成在本地开发中静默失败但在部署时崩溃的代码。

## 为什么这些规则

- **不要使用 `process.env`** 是 AI 代理最常犯的 Cloudflare Workers 错误。在 Node.js 和 Next.js 代码库上训练的代理默认会使用 `process.env.MY_SECRET`。在 Workers 上，这在运行时是 `undefined`——绑定通过 `env` 参数传入，而不是进程环境。
- **使用 `ctx.waitUntil()` 处理副作用** 可以防止一类微妙的数丢失错误。Workers 一旦返回 `Response` 就会终止隔离。任何在响应发送后执行的 `await` 如果没有 `waitUntil` 包裹，都会被静默丢弃，导致分析事件丢失、日志写入失败或数据库更新不完整。

## 适用场景

- Cloudflare Workers API、边缘中间件、基于 Hono 的 Workers 路由器、带有 D1/KV/R2 绑定的 Workers。

## 不适用场景

- Cloudflare Pages Functions（运行时类似，但使用不同的基于文件的路由约定）或通过 `nodejs_compat` 标志启用完整 Node.js API 并故意部署到 Node.js 的项目。