将 TypeScript 代码库从 Inngest SDK…

当需要把现有 TypeScript 项目中的 Inngest v3 迁移到 v4，或修复 v3/v4 API 混用导致的报错时使用。

适用场景

解决思路

1. 先用 rg 扫描所有 Inngest 相关表面：在 package.json 中查找 "inngest"、"@inngest/realtime"、"@inngest/agent-kit"；在代码中查找 new Inngest、EventSchemas、eventType、staticSchema、createFunction(、serve(、connect(、step.invoke、referenceFunction、@inngest/realtime、realtimeMiddleware、useInngestSubscription、serveHost、rewriteGatewayEndpoint、logLevel、streaming:、signingKey、signingKeyFallback、baseUrl、INNGEST_DEV、INNGEST_SIGNING_KEY。
2. 对仓库分类：尚无 Inngest 则改用 inngest-setup；仅 v3 则整体迁移 SDK 与所有破坏性变更；v3/v4 混用则优先从 v4 代码中移除失效的 v3 API；v4 基本完成则聚焦遗漏的运行时陷阱（本地开发模式、serverless maxRuntime、realtime 包导入、字符串 step.invoke）。
3. 编辑前记录迁移扫描清单：当前包版本、客户端文件、serve/connect 入口、使用旧触发语法的函数、EventSchemas 用法、realtime v3 包用法、step.invoke 字符串 ID、serverless 运行时约束、可用的测试/检查。
4. 按顺序升级：1) 更新包版本；2) 修复客户端构造与本地/生产模式；3) 把 serve 选项移到客户端；4) 把触发器移入 createFunction 选项；5) 用 eventType()/staticSchema() 替换 EventSchemas；6) 重写 step.invoke() 字符串 ID；7) 把 realtime 从 @inngest/realtime 迁移到 v4 原生 API；8) 更新中间件与日志；9) 配置 checkpointing/serverless 运行时；10) 类型检查、运行测试，可选与 dev server 同步。
5. 安装最新 v4 SDK：npm install inngest@latest（或 pnpm add inngest@latest / yarn add inngest@latest）。
6. 若仓库使用 v3 realtime，移除 @inngest/realtime；v4 realtime 位于 inngest 包及其子路径（如 inngest/realtime、inngest/react）和原生 step.realtime / inngest.realtime。
7. v4 默认 Cloud 模式；本地开发使用环境变量 INNGEST_DEV=1 npm run dev。除非仓库现有环境模式明确限定为本地代码，否则不要在源码中硬编码 isDev: true；生产应使用 INNGEST_SIGNING_KEY。
8. 把 signingKey、signingKeyFallback、baseUrl 从 serve(...) 移到 new Inngest(...)：旧写法 serve({ client, functions, signingKey, baseUrl })，新写法在 new Inngest({ id, signingKey, baseUrl }) 中配置，serve 只保留 { client, functions }。若仓库已依赖支持的环境变量且未显式传 serve 选项，这些键可能无需改代码。
9. 应用其他重命名：serveHost -> serveOrigin；streaming: "force" -> streaming: true；streaming: "allow" -> streaming: true；streaming: false 保持不变；logLevel 被移除，改为传入 logger，例如 new ConsoleLogger({ level })。
10. 把触发器移入 createFunction 第一个参数的选项对象：旧写法 createFunction({ id }, { event: "user/created" }, handler)，新写法 createFunction({ id, triggers: [{ event: "user/created" }] }, handler)；cron 触发器同样移入 triggers: [{ cron: "0 2 * * *" }]；仅通过 step.invoke 调用的函数可以没有触发器。
11. 用事件级定义替换集中式 EventSchemas：使用 import { Inngest, eventType, staticSchema } from "inngest"，例如 eventType("user/created", { schema: z.object({...}) }) 或 eventType("billing/invoice.paid", { schema: staticSchema<InvoicePaid>() })。
12. 一致使用事件类型：inngest.send(userCreated.create({...}))；createFunction({ id, triggers: [userCreated] }, handler)；step.waitForEvent("wait-for-invoice", { event: invoicePaid, timeout: "7d" })。注意 staticSchema 期望 type 而非 interface，必要时把 interface 转为 type 别名。
13. 重写 step.invoke：v4 不再接受原始字符串函数 ID，改用导入的函数引用或 referenceFunction()，例如 step.invoke("run-report", { function: referenceFunction({ appId: "analytics-app", functionId: "generate-report" }), data: { reportId } })；同代码库目标函数优先直接传导入的函数本身。
14. 迁移 realtime：替换 @inngest/realtime 包、realtimeMiddleware()、handler 参数中的 { publish }、v3 React hooks 如 useInngestSubscription()；改用 inngest/realtime 的 channel 定义、步骤之间的 step.realtime.publish、已有 step.run 内部的 inngest.realtime.publish、以及当前 v4 API 的订阅辅助/hooks。不要在 step.run 内部调用 step.realtime.publish，那里应使用 inngest.realtime.publish 以避免 step 嵌套。
15. 处理并行与 checkpointing：v4 默认启用优化并行与 checkpointing；注意对步骤使用 Promise.race 时，优化并行会让 Promise.race 等待所有 step promise settle，若依赖首个完成行为，改用 group.parallel()。
16. 为 serverless 平台配置 checkpointing 的 maxRuntime 略低于平台限制，例如 new Inngest({ id: "my-app", checkpointing: { maxRuntime: "50s" } })；在 Vercel 等框架上，若平台支持，同时设置路由处理器的 max duration。
17. 若使用 Connect：rewriteGatewayEndpoint 被 gatewayUrl 取代；Connect 可能使用 worker-thread 隔离，出现集成问题时检查 isolateExecution: false 或 INNGEST_CONNECT_ISOLATE_EXECUTION=false；目标 URL 与签名/事件密钥保留在环境变量中。
18. 按递增置信度验证：1) 包管理器安装/更新；2) 类型检查；3) 针对迁移函数的单元/集成测试；4) 用 INNGEST_DEV=1 启动应用；5) 运行 npx inngest-cli@latest dev 并确认函数发现；6) 发送一个代表性事件并检查运行。若无法本地 dev-server 验证，明确说明通过了哪些静态检查以及剩余哪些运行时验证。
19. 针对常见失败信息处理："A signing key is required to run in Cloud mode" 时本地设 INNGEST_DEV=1 或生产配置 INNGEST_SIGNING_KEY；/api/inngest 出现 Cls is not a constructor 时，很可能是 v4 应用中残留 v3 @inngest/realtime 中间件，移除该包并迁移到原生 realtime；step.invoke 字符串函数 ID 失败时改用导入函数引用或 referenceFunction()；schema 类型错误时用 eventType() 和 staticSchema() 替换 EventSchemas；Promise.race 行为异常时用 group.parallel() 处理首个完成的步骤竞争，仅在必要时禁用优化并行。
20. 避免反模式：不要把 v3 realtime 中间件与 inngest@4 混用；不要把 signingKey、baseUrl、signingKeyFallback 传给 serve()；不要只改事件触发语法而忘记 cron/invoke 触发的函数；不要用无类型字符串事件全面替换 EventSchemas；不要在生产源码中硬编码 isDev: true；不要保留 step.invoke 中的字符串 ID；机械迁移后不要跳过类型检查。

适用边界 · 注意事项

• 仓库尚未使用 Inngest 时（应改用 inngest-setup）
• 用户先要求做广泛的代码库可靠性审计时（应先用 inngest-brownfield-audit 确定范围，再回到本迁移）
• 无法进行本地 dev-server 运行时验证时，只能完成静态检查并明确说明剩余验证