Vercel Sandbox 创建即返回就绪实例，首条命令不再等待

Vercel 对其 Sandbox 产品的创建流程做了一处看似微小、实则影响开发者编程习惯的调整：Sandbox.create() 现在只在快照恢复完成后才 resolve，返回的对象是一个已经可以立即执行命令、读写文件的就绪实例。

变化的核心：Promise 语义的修正

在此之前，Sandbox.create() 的 resolve 时机与沙箱真正可用的时机是错位的。开发者拿到 sandbox 对象后执行第一条命令或文件操作时，底层还需要先完成快照恢复，这个等待被隐式地转嫁到了第一个操作上。

新的行为改变了这一语义。创建完成即代表恢复完成，第一个操作不再承担额外的恢复开销。用官方示例来说：

import { Sandbox } from '@vercel/sandbox';

// Resolves after snapshot restoration. Startup failures reject here.
const sandbox = await Sandbox.create();

// Runs without waiting for snapshot restoration.
await sandbox.runCommand('node', ['--version']);

这段代码中，await Sandbox.create() 返回时，runCommand 已经可以直接执行，不需要在内部再做一次等待。

快照恢复（Snapshot Restoration） 是这里的关键机制。沙箱本质上是围绕一次已保存的运行时状态（快照）建立执行环境的过程：快照中包含了文件系统、已安装依赖以及进程内存的镜像，Vercel 需要先把这些数据重新装载到一个可运行的计算实例中，之后才能安全地执行命令或读写文件。这一装载过程并非瞬时完成，它取决于快照大小、是否命中缓存以及底层资源的调度情况。旧版本 API 将这一步延迟到开发者发起第一次操作时才真正触发，导致对象虽然已经返回，但内部还处于"半就绪"状态。新版本把恢复移到 Sandbox.create() 内部完成，使得返回对象与"可执行"状态严格对齐。

错误处理的改善

这次调整带来的另一个实际收益在错误路径上。

按照官方说明，启动阶段的错误现在会直接 reject Sandbox.create()，而不是等到第一个操作时才暴露出来。对于需要在创建沙箱后立即做错误捕获和重试逻辑的开发者来说，这减少了错误定位的复杂度——你知道失败就是创建失败，而不是"创建成功了但第一个命令莫名其妙挂了"。

这种语义上的清晰性，在编写带重试机制的自动化流程时尤其有价值。

Promise 的 reject 语义 在这里也值得说明。在 JavaScript 中，await 一个 Promise 时，如果该 Promise 被 reject，异常会直接在 await 这一行抛出，并可以被同一段 try/catch 捕获。旧行为下，启动失败发生在第一个操作内部，异常从 runCommand 而非 Sandbox.create() 抛出，调用方必须以更宽的范围捕获。新行为把启动错误绑定到创建 Promise 上，调用点的错误归属更精确：Sandbox.create() 抛出的就是创建失败，runCommand() 抛出的就是命令执行失败。这种边界划分让重试策略可以针对不同阶段设置不同逻辑，而不用在同一个 catch 块中判断错误究竟来自哪一步。

时间账：总量不变，分布改变

延迟并没有消失，只是被重新分配了。

快照恢复时间现在计入创建阶段。官方给出的数据是：创建耗时在 p50 增加了约 50 毫秒；对于未缓存的快照，增加幅度可能更大。但关键的一点是——"通过第一个操作的总时间保持不变"。

换句话说，开发者感知到的端到端延迟没有变化，变化的是这段延迟出现在哪个环节。对于单独测量创建耗时的监控面板来说，数字会变高；对于关注"从创建到第一个命令返回"的完整链路来说，表现是一致的。

这种权衡值得注意：它用创建阶段的一点延迟，换取了 API 语义的一致性和错误边界的清晰性。

无需迁移的自动生效

这次变更不需要升级 SDK，也不需要修改任何配置即可生效。官方文档 Sandbox.create() 页面提供了完整细节。

对于已经在使用 Vercel Sandbox 的项目，现有代码不会因此出错——只是行为变得更符合直觉。对于新接入的开发者，API 的契约变得更加直白：创建成功意味着一切就绪。

小结

这是一次典型的"让 API 行为符合语言直觉"的工程改进。Promise 的 resolve 应该意味着"准备好了"，而不是"初始化开始了"。Vercel 把恢复成本从第一个操作前移到了创建阶段，总量不变，但开发者在写代码时少了一层需要记住的隐性规则。对于依赖沙箱做代码执行、CI 任务或 AI Agent 工具调用的场景，这种可预测性的提升比 50 毫秒的分布变化更有意义。