Vercel Workflow SDK：让普通 TypeScript 函数具备持久化执行能力
阅读时间: 大约 10 分钟
Vercel Workflow SDK：让普通 TypeScript 函数具备持久化执行能力
Vercel 在 vercel/workflow 仓库（Apache-2.0，npm 包名 workflow，公开仓库约 2.5k stars）中开源了一套面向 TypeScript/JavaScript 的持久化执行（durable execution）SDK。官方一句话定位是：makes TypeScript and JavaScript functions durable——持久化工作流进度、重试失败步骤、内置可观测性，并且工作流在等待期间可以挂起而不占用计算资源。本文基于仓库 README、本地可观测性截图与官方性能图解，解析它的运行模型与边界。
一、背景：为什么普通异步函数撑不住长流程
Web 服务里最常见的故障模式，是一个流程跨越多步外部调用：发邮件、调支付、等待人工审核、定时提醒、串起多个 LLM 工具调用。传统写法有两条坑：
- 服务是无状态的，实例随时重启、扩容、回收，内存里的进度会丢；
- 失败后只能从头重跑，而发券、扣款、发邮件这类动作不可重复执行，直接重试会造成副作用重复。
持久化执行（durable execution）的通用思路是：在每个可中断点把进度落盘，崩溃后从检查点恢复，配合重试策略与幂等步骤把”长流程”从内存搬到外部状态里。这一领域并不新（Temporal、BullMQ、各种队列 + 调度器方案早已存在），Workflow SDK 的差异在于把这套能力收进一个面向 TS 全栈框架的轻量 SDK，而不是要求团队先引入一套独立编排服务。
二、用法：从 API 路由或 Server Action 启动
按官方 README 的快速上手：
import { start } from 'workflow/api';
import { onboardUser } from './workflows/onboard-user';
await start(onboardUser, ['hello@example.com']);工作流函数本身写成普通的 TS 异步函数，由 SDK 包裹后获得持久化语义。集成层以框架插件形式存在，官方入门指南覆盖 Next.js、Vite、React Router、Astro、Express、Fastify、Hono、Nitro、Nuxt、SvelteKit、TanStack Start 等，其中 Python 与 NestJS 标注为 Beta。本地开发使用自带后端、零配置；部署到 Vercel 时获得托管存储、排队、扩缩容与可观测性；自托管则使用 Postgres 后端，或实现一个自定义的 “World”（官方用 World 这个抽象词指代存储与运行环境适配层）。
调试时在另一个终端运行 npx workflow web 即可打开本地可观测性 UI，查看运行列表、时间线与每一步结果。
三、运行模型：挂起即停算，恢复即续跑
官方对核心机制的公开描述有三点：
- 持久化进度（persists workflow progress）：函数执行到可中断点时，把已完成步骤的结果与位置写入后端存储；
- 失败步骤重试（retries failed steps）：单个步骤失败按策略重试，而不是整段函数重跑；
- 等待时不消耗算力（suspend without using compute while they wait）：工作流
sleep、等待回调或等待外部事件时挂起，运行时不占实例，到点或事件到达再唤醒续跑。
仓库自带的性能图解把这条链路画成”等待前完成工作 → 挂起 → 等待期间零计算 → 唤醒续跑”，并在图注里明确标注 Illustrative timing, not to scale（示意时序，非等比例）。需要注意：这张图是概念示意，图上的时间长短不能当作官方承诺的延迟或开销数字。
本地可观测性时间线里也能直观看到这一结构：截图中的 handleUserSignup 总耗时 5.11s，其中 sleep 一个步骤就占 5.02s——墙钟时间主要花在等待上，而不是 CPU 计算。
四、关键设计点：World 抽象与生命周期钩子
- World 适配层：存储、队列、调度这些与部署环境相关的部分被抽象成 World。本地自带一个零配置后端，Vercel 提供托管实现，Postgres 是自托管起点，第三方自托管/托管方案由社区在 Worlds 页面维护。这意味着同一套工作流代码可以在本地、Vercel、自托管 Postgres 之间切换。
- 生命周期钩子：
registerLifecycleHooks（来自workflow/api）在执行器宿主启动时注册应用级完成与失败上报；官方明确它必须在宿主启动时调用，写在工作流或步骤内部会抛错。 - 文档随包分发：
workflow包把完整文档打进node_modules/workflow/docs，方便编码代理读取与当前版本匹配的指南。
五、评测与口径说明
官方公开材料没有给出统一基准（如每秒恢复次数、单次检查点写放大、冷唤醒延迟），性能图解又自我声明为非等比例示意，因此本文不引用任何具体吞吐或延迟数字。截图中的 5.11s / 5.02s 是单次示例运行的墙钟读数，不代表生产 SLA。评估这类 SDK 时，应在自己的 Postgres 后端、自己的步骤混合（IO 密集/LLM 调用/定时等待）下实测检查点开销与恢复成功率，而不是照搬营销时序图。
六、局限与口径（官方与通用风险）
- Beta 标注：Python 与 NestJS 集成在官方指南中标为 Beta；Koala 项目库也指出整体项目仍处于较早期阶段，生产使用需自行评估稳定性。
- 副作用仍需幂等：持久化保证”不丢进度、可重试”，但扣款、发信、发券等外部副作用是否安全重试，取决于开发者自己把步骤写成幂等；SDK 不会替你解决重复扣款。
- 本地后端 ≠ 生产后端：本地自带后端用于开发调试，托管存储、排队与扩缩容要在 Vercel 或自托管 Postgres 上才有，不能把本地行为当作生产容量预期。
- 并非全新品类：持久化执行不是 Vercel 发明，与 Temporal 等成熟编排器相比，这套 SDK 的强项是嵌入 TS 全栈框架、零独立集群，代价是跨语言、复杂补偿事务（Saga）、大规模多租户编排生态不如专用编排器完整。
- 生态锁定权衡：切到自定义 World 或 Postgres 可降低对 Vercel 的依赖，但托管队列、自动扩缩、托管可观测性等便利能力主要在 Vercel 环境内兑现。
七、适用与不适用
适合：TS 技术栈内的长事务流程（用户 onboarding、订单履约、订阅续费、审批串联）；AI Agent 多步工具调用需要断点续跑；需要”定时等待 + 失败重试 + 可视化时间线”而又不想引入独立 Temporal 集群的中小团队；本地零配置快速原型。
不适合：跨语言异构编排、需要成熟 Saga 补偿与大规模调度治理的企业级流程；对单次检查点写放大极度敏感的超高并发场景；指望 SDK 自动保证外部副作用安全的团队。
八、它意味着什么
Workflow SDK 代表持久化执行继续”框架内化”的趋势：过去需要队列、调度器、状态库三件套拼装的能力，正在被收进全栈框架的依赖里。对 TS 开发者，它降低了长流程的起步门槛；但判断它能否替代成熟编排器，仍要看生产稳定性、自托管完整度与团队的流程复杂度，而不是看本地零配置的顺滑体验。