使用 Vercel Sandbox 进行浏览器自动化

在临时 Vercel Sandbox 微虚拟机中运行 agent-browser + 无头 Chrome。Linux 虚拟机按需启动，执行浏览器命令，然后关闭。适用于任何 Vercel 部署的框架（Next.js、SvelteKit、Nuxt、Remix、Astro 等）。

依赖项

bash
pnpm add @vercel/sandbox

Sandbox 虚拟机需要 Chromium 的系统依赖项以及 agent-browser 本身。使用 sandbox 快照（如下）预安装所有内容，实现亚秒级启动。

核心模式

ts
import { Sandbox } from @vercel/sandbox;

// Sandbox 虚拟机上 Chromium 所需的系统库（Amazon Linux / dnf）
const CHROMIUMSYSTEMDEPS = [
nss, nspr, libxkbcommon, atk, at-spi2-atk, at-spi2-core,
libXcomposite, libXdamage, libXrandr, libXfixes, libXcursor,
libXi, libXtst, libXScrnSaver, libXext, mesa-libgbm, libdrm,
mesa-libGL, mesa-libEGL, cups-libs, alsa-lib, pango, cairo,
gtk3, dbus-libs,
];

function getSandboxCredentials() {
if (
process.env.VERCEL_TOKEN &&
process.env.VERCELTEAMID &&
process.env.VERCELPROJECTID
) {
return {
token: process.env.VERCEL_TOKEN,
teamId: process.env.VERCELTEAMID,
projectId: process.env.VERCELPROJECTID,
};
}
return {};
}

async function withBrowser(
fn: (sandbox: InstanceType) => Promise,
): Promise {
const snapshotId = process.env.AGENTBROWSERSNAPSHOT_ID;
const credentials = getSandboxCredentials();

const sandbox = snapshotId
? await Sandbox.create({
...credentials,
source: { type: snapshot, snapshotId },
timeout: 120_000,
})
: await Sandbox.create({ ...credentials, runtime: node24, timeout: 120_000 });

if (!snapshotId) {
await sandbox.runCommand(sh, [
-c,
sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUMSYSTEMDEPS.join( )} 2>&1 && sudo ldconfig 2>&1,
]);
await sandbox.runCommand(npm, [install, -g, agent-browser]);
await sandbox.runCommand(npx, [agent-browser, install]);
}

try {
return await fn(sandbox);
} finally {
await sandbox.stop();
}
}

截图

screenshot --json 命令将截图保存到文件并返回路径。将文件读取为 base64：

ts
export async function screenshotUrl(url: string) {
return withBrowser(async (sandbox) => {
await sandbox.runCommand(agent-browser, [open, url]);

const titleResult = await sandbox.runCommand(agent-browser, [
get, title, --json,
]);
const title = JSON.parse(await titleResult.stdout())?.data?.title || url;

const ssResult = await sandbox.runCommand(agent-browser, [
screenshot, --json,
]);
const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
const b64Result = await sandbox.runCommand(base64, [-w, 0, ssPath]);
const screenshot = (await b64Result.stdout()).trim();

await sandbox.runCommand(agent-browser, [close]);

return { title, screenshot };
});
}

无障碍快照

ts
export async function snapshotUrl(url: string) {
return withBrowser(async (sandbox) => {
await sandbox.runCommand(agent-browser, [open, url]);

const titleResult = await sandbox.runCommand(agent-browser, [
get, title, --json,
]);
const title = JSON.parse(await titleResult.stdout())?.data?.title || url;

const snapResult = await sandbox.runCommand(agent-browser, [
snapshot, -i, -c,
]);
const snapshot = await snapResult.stdout();

await sandbox.runCommand(agent-browser, [close]);

return { title, snapshot };
});
}

多步骤工作流

Sandbox 在命令之间保持持久化，因此您可以运行完整的自动化序列：

ts
export async function fillAndSubmitForm(url: string, data: Record) {
return withBrowser(async (sandbox) => {
await sandbox.runCommand(agent-browser, [open, url]);

const snapResult = await sandbox.runCommand(agent-browser, [
snapshot, -i,
]);
const snapshot = await snapResult.stdout();
// 解析快照以查找元素引用...

for (const [ref, value] of Object.entries(data)) {
await sandbox.runCommand(agent-browser, [fill, ref, value]);
}

await sandbox.runCommand(agent-browser, [click, @e5]);
await sandbox.runCommand(agent-browser, [wait, --load, networkidle]);

const ssResult = await sandbox.runCommand(agent-browser, [
screenshot, --json,
]);
const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
const b64Result = await sandbox.runCommand(base64, [-w, 0, ssPath]);
const screenshot = (await b64Result.stdout()).trim();

await sandbox.runCommand(agent-browser, [close]);

return { screenshot };
});
}

Sandbox 快照（快速启动）

Sandbox 快照是已安装系统依赖项 + agent-browser + Chromium 的 Vercel Sandbox 的保存虚拟机镜像。可以将其视为 Docker 镜像——无需每次都从头安装依赖项，sandbox 从预构建的镜像启动。

这与 agent-browser 的无障碍快照功能（agent-browser snapshot）无关，后者会转储页面的无障碍树。Sandbox 快照是 Vercel 基础设施概念，用于快速虚拟机启动。

没有 sandbox 快照时，每次运行都需要安装系统依赖项 + agent-browser + Chromium（约 30 秒）。使用快照后，启动时间可缩短至亚秒级。

创建 sandbox 快照

快照必须包含系统依赖项（通过 dnf）、agent-browser 和 Chromium：

ts
import { Sandbox } from @vercel/sandbox;

const CHROMIUMSYSTEMDEPS = [
nss, nspr, libxkbcommon, atk, at-spi2-atk, at-spi2-core,
libXcomposite, libXdamage, libXrandr, libXfixes, libXcursor,
libXi, libXtst, libXScrnSaver, libXext, mesa-libgbm, libdrm,
mesa-libGL, mesa-libEGL, cups-libs, alsa-lib, pango, cairo,
gtk3, dbus-libs,
];

async function createSnapshot(): Promise {
const sandbox = await Sandbox.create({
runtime: node24,
timeout: 300_000,
});

await sandbox.runCommand(sh, [
-c,
sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUMSYSTEMDEPS.join( )} 2>&1 && sudo ldconfig 2>&1,
]);
await sandbox.runCommand(npm, [install, -g, agent-browser]);
await sandbox.runCommand(npx, [agent-browser, install]);

const snapshot = await sandbox.snapshot();
return snapshot.snapshotId;
}

运行一次，然后设置环境变量：

bash
AGENTBROWSERSNAPSHOTID=snapxxxxxxxxxxxx

演示应用中提供了辅助脚本：

bash
npx tsx examples/environments/scripts/create-snapshot.ts

建议用于任何使用 Sandbox 模式的生产部署。

身份验证

在 Vercel 部署中，Sandbox SDK 通过 OIDC 自动进行身份验证。对于本地开发或显