部署 / Cloud

云端浏览器

本地没有屏幕、没有 Chrome，甚至没有一台常驻服务器？chrome-use 一样能跑。把浏览器搬到云上，有两条成熟路径：Vercel Sandbox 的按需 microVM，和 AWS Bedrock AgentCore 的托管云浏览器会话。两者的命令行用法和你在本地敲的几乎一模一样——差别只在于浏览器在哪台机器上运行。

ℹ️ 这一页解决什么

当自动化需要跑在无头环境里——Serverless 函数、CI、定时任务、或者面向用户的 Web 应用后端——就用这一页。如果你想驱动的是自己电脑上正在用的那个 Chrome，请看连接真实 Chrome。

Vercel Sandbox：按需 microVM

Vercel Sandbox 会按需拉起一台 Linux microVM，在里面执行浏览器命令，用完即销毁。它与任意部署在 Vercel 上的框架配合（Next.js、SvelteKit、Nuxt、Remix、Astro 等），并且不受 Serverless 二进制体积限制——因为 Chromium 装在 VM 里，而不是打进你的函数包。

安装依赖

先在你的项目里装上 Sandbox SDK：

bash

$ pnpm add @vercel/sandbox

VM 里则需要 Chromium 的系统库、chrome-use 本身、以及 Chromium 浏览器。首次运行时通过 dnf 安装系统库（Amazon Linux），再用 npm 装 chrome-use，最后跑 chrome-use install 拉取浏览器：

withBrowser.ts

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

// Chromium 在 sandbox VM 上所需的系统库（Amazon Linux / dnf）
const CHROMIUM_SYSTEM_DEPS = [
  "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 withBrowser<T>(
  fn: (sandbox: InstanceType<typeof Sandbox>) => Promise<T>,
): Promise<T> {
  const snapshotId = process.env.AGENT_BROWSER_SNAPSHOT_ID;

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

  if (!snapshotId) {
    await sandbox.runCommand("sh", ["-c",
      `sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} && sudo ldconfig`]);
    await sandbox.runCommand("npm", ["install", "-g", "chrome-use"]);
    await sandbox.runCommand("npx", ["chrome-use", "install"]);
  }

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

✅ 命令与本地一致

VM 起来之后，你在里面跑的就是普通的 chrome-use open、chrome-use snapshot、 chrome-use click……和本地毫无区别。sandbox 只是把这些命令送进 microVM 执行。

截图与快照

screenshot --json 会把图存成文件并返回路径，再把文件读回成 base64 即可传给前端；读取页面结构则用 snapshot -i -c（可交互元素 + 紧凑输出）。sandbox 在多条命令之间会保持存活，所以可以串起完整流程：

screenshotUrl.ts

return withBrowser(async (sandbox) => {
  await sandbox.runCommand("chrome-use", ["open", url]);

  // 拿标题
  const t = await sandbox.runCommand("chrome-use", ["get", "title", "--json"]);
  const title = JSON.parse(await t.stdout())?.data?.title || url;

  // 截图 → 读文件 → base64
  const ss = await sandbox.runCommand("chrome-use", ["screenshot", "--json"]);
  const ssPath = JSON.parse(await ss.stdout())?.data?.path;
  const b64 = await sandbox.runCommand("base64", ["-w", "0", ssPath]);

  await sandbox.runCommand("chrome-use", ["close"]);
  return { title, screenshot: (await b64.stdout()).trim() };
});

多步表单流程

因为 sandbox 在命令之间持久存在，填表 → 提交 → 等待加载 → 截图这样的完整自动化可以一气呵成。典型顺序是 open → snapshot -i 拿到元素 @ref → 逐个 fill → click → wait --load networkidle：

fillAndSubmitForm.ts

await sandbox.runCommand("chrome-use", ["open", url]);
const snap = await sandbox.runCommand("chrome-use", ["snapshot", "-i"]);
// 解析 snapshot，拿到每个字段的 ref…

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

await sandbox.runCommand("chrome-use", ["click", "@e5"]);
await sandbox.runCommand("chrome-use", ["wait", "--load", "networkidle"]);

Sandbox 快照：秒级冷启动

sandbox 快照是一份预装好系统库 + chrome-use + Chromium 的 VM 镜像，类似 Docker image：boot 时直接从镜像启动，不必每次从零安装。没有快照，每次运行要装依赖 + chrome-use + Chromium（约 30 秒）；有快照，启动进入亚秒级。

⚠️ 别混淆两种「快照」

sandbox 快照是 Vercel 的基础设施概念，用于快速启动 VM；它和 chrome-use 的可访问性快照（chrome-use snapshot，导出页面 a11y 树）完全是两回事。

创建一次快照，再把返回的 ID 存进环境变量即可：

bash

# 仓库 demo 里有现成的创建脚本
$ npx tsx examples/environments/scripts/create-snapshot.ts

# 脚本会返回 snapshotId，写进环境变量
$ AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx

✅ 生产环境推荐

任何走 Sandbox 模式的生产部署都建议预建快照，把冷启动从 30 秒压到亚秒级。

鉴权

部署在 Vercel 上时，Sandbox SDK 会通过 OIDC 自动鉴权，无需额外配置。本地开发或需要显式控制时，设置以下三个变量，它们会被展开进 Sandbox.create()；缺省时 SDK 会回退到自动注入的 VERCEL_OIDC_TOKEN：

.env（本地开发）

VERCEL_TOKEN=<personal-access-token>
VERCEL_TEAM_ID=<team-id>
VERCEL_PROJECT_ID=<project-id>

定时任务（Cron）

把 withBrowser 接进 Vercel Cron Jobs，就能做周期性的浏览器任务—— 比如每天早上 9 点抓一次价格页并对比告警：

vercel.json

{ "crons": [{ "path": "/api/cron", "schedule": "0 9 * * *" }] }

Vercel 环境变量一览

变量	必填	说明
`AGENT_BROWSER_SNAPSHOT_ID`	否（推荐）	预建 sandbox 快照 ID，用于亚秒级启动
`VERCEL_TOKEN`	否	Vercel 个人访问令牌（本地开发用；Vercel 上 OIDC 自动）
`VERCEL_TEAM_ID`	否	Vercel team ID（本地开发用）
`VERCEL_PROJECT_ID`	否	Vercel project ID（本地开发用）

同一套模式在各框架下写法一致，只是服务端代码放的位置不同：Next.js 放 server actions / route handlers， SvelteKit 放 +page.server.ts / +server.ts，Nuxt 放 server/api/， Remix 放 loader / action，Astro 放 .astro frontmatter 或 API 路由。完整可跑示例在上游 agent-browser 仓库的 examples/environments/（本仓库未内置，见血统与上游）。

AWS Bedrock AgentCore：托管云浏览器

AgentCore 由 AWS 托管浏览器会话，所有 chrome-use 命令的用法完全不变—— 唯一的区别是浏览器跑在 AWS 上。只要加一个 -p agentcore，其余照旧：

bash

# 在 AgentCore 云浏览器上打开页面
$ chrome-use -p agentcore open https://example.com

# 之后和本地 Chrome 完全一样
$ chrome-use snapshot -i
$ chrome-use click @e1
$ chrome-use screenshot page.png
$ chrome-use close

凭证解析

AWS 凭证会自动解析，已有可用凭证时无需额外配置。解析顺序是：

环境变量 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY（可选 AWS_SESSION_TOKEN）
AWS CLI 回退（aws configure export-credentials），支持 SSO、IAM 角色与命名 profile

bash

# 显式凭证（CI/CD、脚本）
$ export AWS_ACCESS_KEY_ID=AKIA...
$ export AWS_SECRET_ACCESS_KEY=...
$ chrome-use -p agentcore open https://example.com

# SSO（交互式）
$ aws sso login --profile my-profile
$ AWS_PROFILE=my-profile chrome-use -p agentcore open https://example.com

# IAM 角色 / 默认凭证链
$ chrome-use -p agentcore open https://example.com

持久化 Profile：保住登录态

用 AGENTCORE_PROFILE_ID 可以在多次会话之间持久化浏览器状态（cookie、localStorage），非常适合维持登录态：第一次跑登录流程，之后再跑就已经是登录状态了。更完整的登录与会话复用思路见会话管理与登录与鉴权。

bash

# 第一次：登录
$ AGENTCORE_PROFILE_ID=my-app chrome-use -p agentcore open https://app.example.com/login
$ chrome-use snapshot -i
$ chrome-use fill @e1 "user@example.com"
$ chrome-use fill @e2 "password"
$ chrome-use click @e3
$ chrome-use close

# 以后：已是登录态
$ AGENTCORE_PROFILE_ID=my-app chrome-use -p agentcore open https://app.example.com/dashboard

Live View：在控制台实时围观

会话启动时，AgentCore 会往 stderr 打印一个 Live View URL。在浏览器里打开它，就能从 AWS 控制台实时观看这次会话的画面——调试无头流程时特别有用：

stderr

Session: abc123-def456
Live View: https://us-east-1.console.aws.amazon.com/bedrock-agentcore/browser/aws.browser.v1/session/abc123-def456#

选区域 / 用环境变量指定 provider

默认区域是 us-east-1，用 AGENTCORE_REGION 显式切换。如果不想每条命令都带 -p agentcore，可以设 AGENT_BROWSER_PROVIDER：

bash

# 显式区域
$ AGENTCORE_REGION=eu-west-1 chrome-use -p agentcore open https://example.com

# 用环境变量固定 provider，命令就不用再带 -p
$ export AGENT_BROWSER_PROVIDER=agentcore
$ export AGENTCORE_REGION=us-east-2
$ chrome-use open https://example.com
$ chrome-use snapshot -i
$ chrome-use close

AgentCore 环境变量一览

变量	说明	默认值
`AGENTCORE_REGION`	AWS 区域	`us-east-1`
`AGENTCORE_BROWSER_ID`	浏览器标识	`aws.browser.v1`
`AGENTCORE_PROFILE_ID`	持久化浏览器 profile（cookie、localStorage）	（无）
`AGENTCORE_SESSION_TIMEOUT`	会话超时（秒）	`3600`
`AWS_PROFILE`	用于凭证解析的 AWS CLI profile	`default`

常见问题

⚠️ 排错清单

Failed to run aws CLI：AWS CLI 没装或不在 PATH。装上，或直接设 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。
AWS CLI failed: ... Run 'aws sso login'：SSO 凭证过期，跑一次 aws sso login 刷新。
会话超时：默认 3600 秒（1 小时）。长任务用 AGENTCORE_SESSION_TIMEOUT=7200 拉长。

两条路径怎么选

▲ Vercel Sandbox

已经在 Vercel 上部署应用、想要按需拉起即用即销的 microVM，且不愿被 Serverless 二进制体积限制卡住时选它。用 sandbox 快照拿到秒级冷启动。

☁︎ AWS Bedrock AgentCore

身处 AWS 生态、想要托管的云浏览器会话、需要持久化 profile 保住登录态、或想在控制台 Live View 实时围观时选它。命令行体验与本地零差别。

ℹ️ 相关阅读

想驱动本机 Chrome 而非云端，见连接真实 Chrome；跨会话复用登录态的通用做法，见会话管理。