用途:为 TypeScript 项目提供 Cloudflare Workers 与 Durable Objects 的开发约定,配套 Spiceflow + Vite + @cloudflare/vite-plugin 框架组合。入口固定为 src/app.tsx,同时导出默认 fetch 处理器与 DO 类,不使用独立 worker.ts。
主要能力:后台任务必须用 waitUntil,避免响应发送后 isolate 被回收导致 Promise 被丢弃;配置统一用 wrangler.jsonc,compatibility_date 取当天减 30 天,以启用 WeakRef 等新 API;跨自域 fetch 需加 global_fetch_strictly_public;TCP socket 无法访问 Cloudflare 自身 IP,HTTP 请改用 fetch。
类型安全:用 wrangler types 生成 worker-configuration.d.ts,替代 @cloudflare/workers-types;使用 nodejs_compat 时安装 @types/node;不要自定义 Env 接口。DO 优先用命名 RPC 方法而非覆写 fetch,并通过 helper 修正 DurableObjectNamespace 泛型。
密钥与本地开发:在 wrangler.jsonc 的 secrets.required 声明密钥;本地用 Doppler 注入(需 CLOUDFLARE_INCLUDE_PROCESS_ENV=true),部署用 wrangler secret bulk,首次部署可借 --secrets-file 解决先有鸡还是先有蛋问题。KV 命令行务必加 --remote。静态资源 CORS 用 public/_headers 配置。注意 KV.list 始终最终一致,验证写入建议用 getWithMetadata。
限制:以上为项目约定的操作规范,涉及具体价格、平台支持范围及效果暂未提供。