返回博客2026年1月22日

Vercel AI SDK 沙箱全解析：从 Edge Runtime 到 Firecracker MicroVM

VercelAI SDKSandboxEdge RuntimeFirecracker

为什么 AI Agent 需要沙箱？

AI Agent 最强大的能力之一是生成并执行代码。但这也带来了巨大的安全风险：

  • 恶意代码执行：AI 可能生成删除文件、窃取数据的代码
  • Prompt Injection：用户可能诱导 AI 执行非预期操作
  • 资源滥用：无限循环、内存泄漏可能拖垮服务器

在你的机器或生产环境直接运行 AI 生成的代码？这事儿想想就危险。沙箱的作用就是提供一个隔离的执行环境，让代码在受控边界内运行。

Vercel 在这方面提供了两层隔离方案，适用于不同场景：

方案隔离技术适用场景
Edge RuntimeV8 Isolates轻量计算、API 路由、Middleware
Vercel SandboxFirecracker MicroVM完整 Linux 环境、AI 代码执行

Edge Runtime：V8 Isolates 的轻量隔离

先说说 Vercel 的边缘计算方案 Edge Runtime。它基于 V8 JavaScript 引擎的 Isolates 技术实现隔离，是一种非常轻量的方案。

什么是 V8 Isolates？

V8 Isolates 是 V8 引擎提供的轻量级执行上下文。每个 Isolate 拥有独立的内存空间，但共享同一个运行时进程。听起来有点抽象，看图更直观：

flowchart TB
    subgraph Process["V8 进程"]
        I1["Isolate A<br/>~10KB"]
        I2["Isolate B<br/>~10KB"]
        I3["Isolate C<br/>~10KB"]
    end

    subgraph Traditional["传统容器"]
        C1["Container<br/>~10MB+"]
    end

V8 Isolates vs 传统容器

性能优势相当明显：

指标V8 Isolates传统 Serverless
冷启动~1ms~100ms
内存开销~10KB~10MB
全球延迟极低中等

10KB vs 10MB，100 倍的差距。这就是为什么 Edge Runtime 能做到毫秒级冷启动。

安全边界

Edge Runtime 的安全性来自严格的 API 限制 - 简单粗暴但有效：

  • ❌ 无文件系统访问（fs）
  • ❌ 无子进程（child_process）
  • ❌ 无原生模块（net、crypto 原生版本）
  • ✅ 只支持 Web 标准 API（fetch、Request、Response）

这种设计使得恶意代码几乎无法造成破坏，因为它根本没有能力访问系统资源。你想删文件？没有 fs。想执行 shell 命令？没有 child_process。

限制

当然，Edge Runtime 并非万能：

  • 包大小限制：单个 Edge Function 最大 1MB（解压后）
  • 无重型库：sharp、puppeteer、bcrypt 等无法使用
  • 执行时间限制：Hobby 计划 30 秒，Pro/Enterprise 300 秒

结论：Edge Runtime 适合轻量计算，但不适合执行 AI 生成的任意代码。毕竟 AI 可能想用 pandas 做数据分析，可能想调用系统命令，这些 Edge Runtime 都搞不定。

Vercel Sandbox：Firecracker MicroVM 的完整隔离

当你需要运行任意代码 - 尤其是 AI 生成的不可信代码 - Vercel Sandbox 是更合适的选择。

架构概览

Vercel Sandbox 的底层是 Firecracker - AWS 开源的 MicroVM 技术。这可不是什么小项目，AWS Lambda 和 Fargate 的底层就是它。Vercel 能用上同款技术，说明他们在基础设施上确实下了功夫。

flowchart TB
    subgraph Vercel["Vercel 基础设施"]
        subgraph MicroVM["Firecracker MicroVM"]
            FS["独立文件系统"]
            Net["隔离网络"]
            Proc["独立进程空间"]
            Runtime["Node.js / Python"]
        end
    end

    User["用户代码"] -->|"SDK 调用"| MicroVM
    MicroVM -->|"结果返回"| User

Firecracker MicroVM 架构

每个 Sandbox 是一个独立的 Linux MicroVM，具有：

  • 独立的文件系统
  • 独立的进程和网络命名空间
  • 完整的 sudo 权限
  • Amazon Linux 2023 基础环境

换句话说，这就是一台"真正的"Linux 机器，只不过是按需创建、用完即销毁。

可用运行时

目前 Sandbox 支持三种运行时，可以在 SDK 文档 查看完整配置：

运行时路径包管理器
node24 (默认)/vercel/runtimes/node24npm, pnpm
node22/vercel/runtimes/node22npm, pnpm
python3.13/vercel/runtimes/pythonpip, uv

Python 3.13 + uv，这配置挺新的。对于数据分析、机器学习类的 Agent 来说够用了。

资源配置

配置项范围
vCPU最多 8 个
内存每 vCPU 2GB
默认超时5 分钟
最大超时Hobby 45 分钟 / Pro 5 小时
可暴露端口最多 4 个

8 vCPU + 16GB 内存，跑个数据分析脚本绰绰有余。

AI SDK 6 代码执行集成

Vercel 在 AI SDK 6 中引入了原生的代码执行工具，和 Sandbox 深度集成。这意味着你不需要自己处理 Sandbox 的创建和管理，SDK 帮你搞定。

安装

pnpm add ai-sdk-tool-code-execution

基本用法

import { generateText, stepCountIs } from 'ai';
import { executeCode } from 'ai-sdk-tool-code-execution';

const { text } = await generateText({
  model: 'openai/gpt-4o',
  prompt: '计算 2^100 的精确值',
  tools: {
    executeCode: executeCode(),
  },
  stopWhen: stepCountIs(5),
});

console.log(text);

就这么简单。AI 会自动决定是否需要执行代码，生成 Python 代码，在 Sandbox 中运行，然后把结果返回。

工作原理

sequenceDiagram
    participant App as 应用
    participant SDK as AI SDK
    participant LLM as 语言模型
    participant Sandbox as Vercel Sandbox

    App->>SDK: generateText(prompt, tools)
    SDK->>LLM: 发送 prompt
    LLM-->>SDK: 返回 tool call (executeCode)
    SDK->>Sandbox: 创建 MicroVM，执行代码
    Sandbox-->>SDK: 返回执行结果
    SDK->>LLM: 将结果加入上下文
    LLM-->>SDK: 生成最终回答
    SDK-->>App: 返回结果

AI SDK 代码执行流程

认证方式

认证有两种方式，详见 认证文档：

1. Vercel OIDC Token（推荐）

如果你的项目部署在 Vercel 上，这是最省心的方式。本地开发时，运行 vercel env pull 获取 token：

vercel link
vercel env pull

生产环境中，Vercel 自动管理 token，你完全不用操心。

2. Access Token

如果你的应用不在 Vercel 上运行，就需要手动配置：

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

const sandbox = await Sandbox.create({
  teamId: process.env.VERCEL_TEAM_ID,
  projectId: process.env.VERCEL_PROJECT_ID,
  token: process.env.VERCEL_TOKEN,
  runtime: 'python3.13',
});

Sandbox SDK 详解

如果你想要更精细的控制，可以直接使用 @vercel/sandbox 包。它提供了完整的编程接口，让你能完全掌控 Sandbox 的生命周期。

安装

pnpm add @vercel/sandbox

核心 API

创建 Sandbox

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

const sandbox = await Sandbox.create({
  runtime: 'node24',
  timeout: 5 * 60 * 1000, // 5 分钟
  ports: [3000],
  resources: { vcpus: 4 },
});

执行命令

// 同步执行
const result = await sandbox.runCommand('node', ['--version']);
console.log(await result.stdout()); // v24.x.x

// 使用 sudo
await sandbox.runCommand({
  cmd: 'dnf',
  args: ['install', '-y', 'golang'],
  sudo: true,
});

没错，你可以在 Sandbox 里用 sudo。想装什么包就装什么包。

文件操作

// 写入文件
await sandbox.writeFiles([
  { path: 'index.js', content: Buffer.from('console.log("Hello")') }
]);

// 读取文件
const content = await sandbox.readFileToBuffer({ path: 'output.txt' });

// 创建目录
await sandbox.mkDir('src/components');

获取公开 URL

这个功能挺有意思 - 你可以在 Sandbox 里启动一个 Web 服务，然后获取一个公开 URL：

// 启动开发服务器
await sandbox.runCommand({
  cmd: 'npm',
  args: ['run', 'dev'],
  detached: true,
});

// 获取可访问的 URL
const previewUrl = sandbox.domain(3000);
console.log(previewUrl); // https://xxx.vercel.dev

这对于 AI 生成前端代码然后实时预览的场景非常实用。

快照功能

快照可以保存 Sandbox 状态，加速后续启动。比如你装了一堆依赖，可以保存快照，下次直接从快照恢复：

// 创建快照（会自动停止 sandbox）
const snapshot = await sandbox.snapshot();
console.log(snapshot.snapshotId);

// 从快照恢复
const newSandbox = await Sandbox.create({
  source: { type: 'snapshot', snapshotId: snapshot.snapshotId },
});

不过要注意，快照 7 天后会过期，具体可以看 定价文档。

实际应用场景

说了这么多 API，来看几个实际的应用场景。

1. AI Coding Agent

Vercel 提供了一个 Coding Agent 模板，展示了如何构建 AI 编程助手：

import { Sandbox } from '@vercel/sandbox';
import { generateText } from 'ai';
import { executeCode } from 'ai-sdk-tool-code-execution';

// AI 生成代码并在 Sandbox 中执行
const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-20250514',
  system: '你是一个 Python 专家，使用代码解决问题',
  prompt: '分析这个 CSV 数据并生成报告',
  tools: {
    executeCode: executeCode(),
  },
});

2. 交互式代码预览

这个场景很适合做在线 IDE 或代码教学平台：

// 从 Git 仓库创建 Sandbox
const sandbox = await Sandbox.create({
  source: {
    type: 'git',
    url: 'https://github.com/user/repo.git',
  },
  ports: [3000],
});

// 安装依赖并启动
await sandbox.runCommand('pnpm', ['install']);
await sandbox.runCommand({
  cmd: 'pnpm',
  args: ['dev'],
  detached: true,
});

// 获取预览 URL
const url = sandbox.domain(3000);

用户提交代码，后端创建 Sandbox，启动预览，返回 URL。整个流程全自动。

3. 数据分析 Agent

Python 数据分析是 AI Agent 最常见的用途之一：

const sandbox = await Sandbox.create({ runtime: 'python3.13' });

// 安装数据分析库
await sandbox.runCommand('pip', ['install', 'pandas', 'matplotlib']);

// 上传数据文件
await sandbox.writeFiles([
  { path: 'data.csv', content: csvBuffer }
]);

// 执行分析脚本
const result = await sandbox.runCommand('python', ['analyze.py']);

定价

这么有用的资源和服务，当然是要收费的。Sandbox 目前处于 Beta 阶段。我们参考 定价页面，来看看当前的计价情况：

免费额度（Hobby 计划）

资源免费额度/月
CPU 时间5 小时
内存420 GB-hr
网络带宽20 GB
Sandbox 创建数5,000 次

5 小时 CPU 时间，对于个人项目或原型开发来说基本够用。

Pro/Enterprise 计价

资源单价
CPU$0.128/小时
内存$0.0106/GB-hr
网络$0.15/GB
创建数$0.60/百万次

CPU $0.128/小时，比 EC2 按需实例贵一些，但考虑到按需创建、自动销毁、无需运维，这个价格还算合理。

与其他方案对比

市面上做 AI 代码执行沙箱的不止 Vercel 一家，简单对比一下：

方案隔离技术冷启动语言支持适用场景
Vercel EdgeV8 Isolates~1msJS/TS轻量 API、Middleware
Vercel SandboxFirecracker~秒级Node.js, PythonAI 代码执行
E2BFirecracker~150ms多语言通用云端沙箱
AWS LambdaFirecracker~100ms多语言通用 Serverless

Vercel Sandbox 的优势在于与 AI SDK 的深度集成和 Vercel 生态的无缝连接。如果你的应用本身就部署在 Vercel 上，用它是最省心的选择。

安全最佳实践

虽然 Sandbox 本身已经提供了很好的隔离，但在使用时还是要注意一些安全细节：

  1. 最小权限原则：只授予必需的资源和端口
  2. 设置超时：避免无限运行消耗资源
  3. 输出验证：AI 生成的代码输出也需要验证
  4. 网络隔离：考虑是否需要禁用出站网络
const sandbox = await Sandbox.create({
  runtime: 'python3.13',
  timeout: 60 * 1000, // 1 分钟超时
  resources: { vcpus: 2 }, // 限制 CPU
  // 不暴露端口 = 无入站访问
});

不暴露端口、限制 CPU、设置短超时 - 这些都是防止滥用的有效手段。

总结

Vercel 提供了两种不同级别的隔离方案：

Edge RuntimeVercel Sandbox
隔离技术V8 IsolatesFirecracker MicroVM
隔离强度中等（API 限制）强（完整 VM）
性能极快冷启动秒级启动
能力有限 API完整 Linux
适用场景轻量计算AI 代码执行

对于 AI Agent 应用，推荐组合使用：

  • Edge Runtime：处理 API 路由、用户请求
  • Vercel Sandbox：执行 AI 生成的代码

AI SDK 6 的 executeCode 工具让这一切变得简单 - 只需几行代码，就能让你的 AI 安全地执行代码。

参考资料

官方文档

示例模板

技术背景

往期回顾

准备开始了吗？

先简单说明目标，我会给出最合适的沟通方式。

预约 30 分钟邮件联系