04 — TypeScript 工程化与落地（怎么解决）¶

本章回答「若选定 Cloudflare + TS，工程上如何做」：脚手架、类型生成、本地开发、全栈框架与观测。

1. 项目 bootstrap¶

官方推荐用 C3（npm create cloudflare@latest）创建项目，可选择 TypeScript 模板与 Hello World/Worker only 等起点；生成物通常包含：

wrangler.json / wrangler.toml：绑定、兼容日期、路由与限制等；
src/index.ts：最小 fetch 处理器；
tsconfig.json：含 Workers 类型。

参考教程片段见：connect-to-turso tutorial — Wrangler

2. 类型：`wrangler types` 与 `@cloudflare/workers-types`¶

官方说明：TypeScript is a first-class language；类型与开源运行时 workerd 对齐。
运行 wrangler types 可生成与 bindings 匹配的 Env 等定义，减少 env 拼写错误。
也可安装 @cloudflare/workers-types 作为补充（见 TypeScript 文档）。

多环境：changelog 记载，wrangler types 默认可聚合各 environment 的 bindings；若只需单一环境可用 --env。

参考：wrangler types multi-environment (changelog)

3. RPC / Service Bindings 的端到端类型¶

对 Worker 间 RPC，文档展示通过 wrangler types 生成：

Service<YourEntrypoint>
DurableObjectNamespace<YourDO>

从而在客户端 Worker 里方法级类型安全（await env.SUM_SERVICE.sum(1, 2) 等）。

参考：RPC TypeScript

4. 本地开发：Wrangler、`getPlatformProxy`、Vite¶

wrangler dev：本地跑 Worker；部分绑定可用 remote bindings 连真实资源（见 R2 Workers 文档 Local Development 说明）。
Wrangler API：getPlatformProxy 可在 Node 进程里模拟绑定，便于框架集成测试（Nuxt 等文档引用该 helper）。

参考：

5. 全栈框架 targeting Workers¶

官方列举在 Workers 上原生支持的 full-stack 框架（Astro、React Router/Remix、Next.js、Nuxt、Solid、Qwik 等），统一走「构建 HTML + 静态资源 + Worker 脚本」的模式。

参考：Full-stack application

从 Pages 迁到 Workers：若当前是 Pages Functions 或 _worker.js advanced mode，文档给出 .assetsignore、改 main 与 assets.directory 等步骤。

参考：Migrate from Pages to Workers

6. 平台 API 与自动化（Typescript SDK）¶

Changelog 提到面向 Workers 的 REST API Beta 与 Cloudflare TypeScript SDK，便于平台团队用 Terraform/SDK 管理脚本与部署，开发团队在另一仓库发版（分工边界更清晰）。

7. 运行时注意点（TS 层实践）¶

ExportedHandler<Env> / satisfies：在 fetch(request, env, ctx) 上标注返回 Promise<Response>，与官方示例一致。
避免全局可变状态；需要 LRU 等缓存时务必评估并发与驱逐。
为 CPU 热点做 profiling：官方建议本地 CPU profiling 与 Workers Logs 中的 CPU 时间字段。

参考：Error 1102 — exceeded limits

8. D1、AI、Vectorize 等 binding 的类型¶

在 Wrangler 中声明 d1_databases、ai、vectorize 等后，同样应 wrangler types 刷新 Env，避免手写 Env 与生产配置漂移。官方示例中 Workers AI 入门教程给出带 AI: Ai 的 Env（可改由生成文件承接）。

产品与模式梳理见：06 — 数据层、AI、向量与 RAG。

下一篇：未来挑战与方向。