Cloudflare Workers Testing with Vitest 是一套针对 Cloudflare Workers 的测试方案指南，核心是使用 Vitest 搭配 @cloudflare/vitest-pool-workers，在真实的 Workers 环境中编写并运行单元测试与集成测试，并支持完整的绑定能力，包括 D1、KV、R2、Durable Objects、Queues 与 AI。测试在 Miniflare 中执行，用于本地开发，并可在 CI/CD 中运行，以贴近实际的 Workers 运行时行为。
主要能力 资料列出的关键能力包括：绑定（binding）相关的测试支持、执行上下文（execution context）测试、边缘运行时模拟、覆盖率跟踪，以及较快的测试执行。
版本与更新（2025） 文档标注状态为生产可用，最后验证日期为 2025-01-27。资料给出依赖版本：Vitest ^2.0.0、@cloudflare/vitest-pool-workers 0.7.2、Miniflare 为最新版本。 @cloudflare/vitest-pool-workers 0.7.2（2025 年 1 月）的变更说明包括：破坏性变更——Miniflare v3，要求 Node.js 20+；新增 cloudflare:test 模块，用于访问 env/ctx；改进绑定使用的隔离存储速度；修复 worker 到 worker 的 service bindings；新增对 Vectorize 与 Workers AI 绑定的支持。 迁移旧版本时，资料给出的依赖更新命令为：
Update dependencies
bun add -D vitest@^2.1.8 @cloudflare/vitest-pool-workers@^0.7.2
并给出新的 pool 配置格式示例： export default defineWorkersConfig({ test: { poolOptions: { workers: { wrangler: { configPath: './wrangler.jsonc' }, miniflare: { compatibilityDate: '2025-01-27' } } } } });
快速开始（5 分钟） 资料给出的步骤为：
- 安装依赖：bun add -D vitest @cloudflare/vitest-pool-workers
- 创建 vitest.config.ts（引用 defineWorkersConfig，配置 poolOptions.workers.wrangler.configPath 与 miniflare compatibilityDate / compatibilityFlags）。
- 编写第一个测试（使用 vitest 与 cloudflare:test，调用 worker.fetch 并使用 createExecutionContext 与 waitOnExecutionContext）。
- 运行测试：bun test 或 bunx vitest。
关键规则（Critical Rules） 资料强调的规则包括：
- 始终通过 cloudflare:test 获取 env，不要手动创建 env 对象；这样可使用从 wrangler.jsonc 配置的真实绑定，并在每个测试中获得隔离存储。
- 始终等待执行上下文（waitOnExecutionContext），因为 Workers 使用 ctx.waitUntil() 处理后台任务，不等待可能导致任务未完成。
- 每个测试都有隔离存储；每个测试使用全新的绑定存储。
- 使用 Wrangler 配置来定义绑定；没有 Wrangler 配置时 env 会为空。
- 匹配 compatibility date，使测试环境与生产运行时行为一致。
核心概念 绑定测试模式给出了 D1、KV、R2、Durable Objects 的示例用法（插入/查询 D1、读写 KV、上传/读取 R2、通过 idFromName/get 调用 Durable Object 并验证状态）。 单元测试与集成测试的区别：单元测试针对单个函数（如 validateInput），集成测试针对完整的 fetch handler（构造 Request，调用 worker.fetch，等待执行上下文，再断言响应）。 覆盖率配置：在 vitest.config.ts 中配置 coverage（provider 为 v8，reporter 为 text/json/html，include/exclude，以及 lines/functions/branches/statements 的 thresholds），并使用 bunx vitest run --coverage 运行。
典型用例（Top 5 Use Cases） 资料给出五类用例：结合 D1 测试 API 端点（创建用户并校验数据库插入）、使用 KV 测试缓存（验证 X-Cache 为 MISS/HIT）、测试向 R2 上传文件（表单上传后校验 R2 对象内容）、测试 Durable Objects 状态（多次 increment 后校验计数值）、测试 Queue consumers（构造 messages 后调用 worker.queue 并校验处理结果）。
最佳实践 建议的做法包括：使用描述性测试名、测试错误场景（如无效 JSON 返回 400）、按 describe 分组相关测试、使用 beforeEach 做初始化、测试并发请求等真实场景。 不建议的做法包括：在测试间共享状态、忘记等待执行上下文、硬编码 URL、测试实现细节而非行为。
常见错误与预防（Top 8） 资料列出并给出修复方式的常见问题包括：env is not defined（需从 cloudflare:test 导入 env）；Cannot read property 'DB' of undefined（需在 vitest.config.ts 中加载 wrangler.jsonc）；D1_ERROR: no such table（需在测试前建立 schema，可在 beforeEach 执行建表或加载迁移）；ctx.waitUntil tasks did not complete（需 await waitOnExecutionContext(ctx)）；SELF is not defined（应改用直接导入 worker 的现代模式）；KV.get() 返回上一测试数据（需避免共享变量导致测试污染）；env.BUCKET.put is not a function（需在 wrangler.jsonc 配置 R2 绑定）；Pool 'workers' is not supported（需安装 @cloudflare/vitest-pool-workers）。
适用场景与限制 该指南适用于为 Cloudflare Workers 编写单元测试与集成测试、需要模拟边缘运行时并测试 D1/KV/R2/Durable Objects/Queues/AI 等绑定的场景，也适用于在本地 Miniflare 中开发并在 CI/CD 中运行测试。资料明确提示 Miniflare v3 需要 Node.js 20+，并强调绑定来自 wrangler 配置、兼容性日期需与生产保持一致。除此之外，关于收费、价格、平台、具体效果或其他未在资料中出现的细节，暂未提供。