Cloudflare Workers 项目创建与类型方案

1. worker-configuration.d.ts 是什么

由 npx wrangler types 自动生成的 TypeScript 类型声明文件，作用是给 TS 提供 Workers 环境的全局类型：

• 绑定类型（Env）：顶部定义 Env 接口，代表 wrangler.jsonc 里配置的变量和绑定（KV、D1、secrets）。代码里 satisfies ExportedHandler 和 request, env 依赖它。
• 运行时类型（占 99%+，约 1.4 万行）：声明 fetch、crypto、WebSocket、D1Database、ExecutionContext 等内置 API 的类型。

它是构建产物，由 wrangler 生成，不是手写的。改了 wrangler.jsonc 后需重新跑 wrangler types。

2. 为什么有的项目不需要它（新旧方案对比）

| | 旧方案 | 新方案（推荐） |

|---|---|---|

| 类型来源 | npm 包 @cloudflare/workers-types | 生成的 worker-configuration.d.ts |

| 配置 | tsconfig.json 的 "types": ["@cloudflare/workers-types"] | tsconfig 加生成文件路径 |

| Wrangler 版本 | v3（wrangler.toml + Pages Functions） | v4+（wrangler.jsonc + wrangler types） |

旧项目（如 taptrans-cloud）用 Cloudflare Pages + @cloudflare/workers-types 包获取全局类型，所以不需要生成文件。两者目的相同，只是版本和来源方式不同。

3. 官方推荐的新方案

官方明确建议用 wrangler types 而非 @cloudflare/workers-types 包：

• 生成的文件基于 Worker 的 compatibility date + compatibility flags，类型与实际运行时 API 完全一致。
• workers-types 包是静态快照，无法覆盖每种组合。

迁移步骤：卸载 @cloudflare/workers-types → 跑 npx wrangler types → 在 tsconfig 的 "types" 里加生成文件。注意：

• @cloudflare/workers-types 不会停止发布，官方仍推荐用它给库和共享包写类型。
• 使用 nodejs_compat 时需额外装 @types/node。

为什么类型不放进 npm 包

worker-configuration.d.ts 的内容是"个性化"的，无法塞进静态 npm 包：

• 绑定类型（Env）：每个项目的 KV、D1、AI、secrets 名字都不同，npm 包无法预知。
• 运行时类型：随 compatibility date 和 flags 变化，npm 包只能固定发版时的一套。

所以 wrangler types 在本地基于配置现场生成，保证类型与实际运行时 100% 一致。类比：workers-types 是"通用说明书"，生成文件是"量身定做的说明书"。

4. create-cloudflare 模板说明

| 模板 | 用途 |

|---|---|

| Worker only | 最简单的 Worker，一个 fetch 处理器，只做 HTTP 接口。适合简单 API、代理、webhook |

| Static site | 托管静态文件（HTML/CSS/JS），用 Workers Assets 直接 serve，无后端逻辑。适合落地页、纯前端站点 |

| SSR / full-stack app | Worker 渲染页面（服务端渲染），前后端一体。适合需要 SEO 或动态页面的全栈应用，通常配框架（Remix/Next/Vite） |

| Worker + Durable Objects | Worker 加 Durable Object（有状态、单点协调的类）。适合聊天室、协同编辑、游戏房间 |

| Worker + DO + Assets | 上面那套再加静态资源托管，全栈 + 有状态 + 静态资源一体 |

| Workflow | 用 Workflows 定义持久化的多步任务（有重试、暂停/恢复）。适合异步流水线 |

| Scheduled Worker (Cron Trigger) | 按 Cron 定时触发的 Worker，不处理请求。适合定时任务、监控、清理数据 |

| Queue consumer & producer | 用 Queues 做生产者/消费者模式，解耦任务、削峰。适合事件驱动、异步处理 |

| API starter (OpenAPI compliant) | 生成符合 OpenAPI 规范的 API 骨架，自带文档和类型校验 |

常见误解澄清

• "Worker + DO + Assets" 不是 SSR：DO 提供有状态、可协调的存储与实时通信；Assets 是静态文件托管；SSR 是服务端渲染 HTML。三者是不同维度的概念，可以组合。
• Assets 不是 SSR：Assets 指 Workers Assets，静态文件托管，通过 CDN 边缘分发，不经过 Worker 代码执行。SSR 是动态执行代码生成 HTML。两者互补：静态资源走 Assets，动态页面走 Worker。
• Worker + DO 模板能加 SSR：SSR 本质是 Worker 的 fetch 里返回 HTML，和 DO 不冲突。DO 负责有状态部分，Worker 渲染页面，Assets 托管静态资源。

5. 能力是随时能加的

所有"能力"都不是模板锁死的，本质是两块可后加的东西：

1. wrangler.jsonc 里的配置（assets、durable_objects、triggers、queues、ai 绑定等）

2. 代码里对应的逻辑

| 想加的能力 | 加什么 |

|---|---|

| Static site / Assets | wrangler.jsonc 加 assets.directory + 建 public/ 目录 |

| Durable Objects | 加 durable_objects.bindings + 定义一个 class + export |

| Cron | 加 triggers cron 配置 + 处理 scheduled 事件 |

| Queue | 加 queues 生产者/消费者配置 |

| Workflow | 加 workflows 绑定 + 定义 workflow 类 |

| SSR / 框架 | 引入 Hono/Remix 等，替换 fetch 逻辑 |

改完跑 npx wrangler types 刷新类型、wrangler deploy 部署。模板只是起步脚手架，选 "Worker only" 后面加任何能力都不受限。唯一相对麻烦的是 SSR 配框架（需要引入构建工具链，只是工程化成本，不是平台限制）。

6. OpenAPI 规范是什么

OpenAPI 规范（原 Swagger）是一个描述 HTTP API 的开放标准——用统一的 YAML/JSON 格式，声明 API 的路径、方法、参数、请求/响应体结构。它不关心代码实现，只描述接口长什么样。

解决的问题：

• 文档自动化：schema 可渲染成交互式文档（如 Swagger UI），不用手写
• 校验与类型：工具按 schema 自动校验请求、生成客户端代码和 TS 类型
• 前后端对齐：多方按同一份契约开发，避免"文档和代码不一致"

API starter 模板的卖点：用一套 TypeScript 定义定义 API 结构，运行时校验、类型安全、交互式文档全部自动推导。适合对外提供 API、需第三方调用的接口、希望文档与实现同步的场景。

类比：OpenAPI 之于 HTTP API，就像 XML Schema 之于 XML、DDL 之于数据库表结构。