企业官网建设流程全解析

• CLI
• 后端
• 云原生

vercel sandbox是 Vercel CLI 内建的沙箱入口命令，它将所有参数转发给独立的 Sandbox CLI，用于在 Vercel 平台上创建和管理项目级（project-scoped）沙箱环境。本文以 sandbox.md 为骨架，结合仓库中 sandbox 命令源码 的实现细节，完整讲解list、create、run、exec、connect、copy、stop、config、snapshot、snapshots、login/logout全部子命令的用法、--参数分隔约定、认证令牌转发机制，以及在使用沙箱前必须注意的安全事项。读完本文，你将能熟练地在终端里完成"创建沙箱 → 执行命令 → 复制文件 → 生成快照 → 停止回收"的完整工作流。

一、vercel sandbox概览：一条命令背后的转发机制

vercel sandbox本身并不实现沙箱逻辑，而是**原样转发（forward）**给 Sandbox CLI 来处理项目级沙箱环境。从仓库源码可以确认这条转发链路：

• commands/sandbox/index.ts 是vercel sandbox的默认导出入口，负责解析并转发参数；
• 在 commands/index.ts 中注册sandboxCommand命令定义，其描述为Interact with Vercel Sandbox；
• 在 commands-bulk.ts 中通过export { default as sandbox } from './commands/sandbox'批量导出；
• 在 index.ts 中按命令名动态加载sandbox实现；
• 依赖方面，package.json 声明了"sandbox": "3.4.0"，转发的目标正是这个独立的sandboxnpm 包。

由于沙箱子命令集合会随 Sandbox CLI 版本演进，官方推荐的权威做法是随时运行：

vercel sandbox --help

以获取当前版本支持的最新的子命令与参数列表。下文列出的子命令均通过sandbox/index.ts接线，属于当前文档确认的稳定命令面。

二、子命令速查表

以下为vercel sandbox的完整子命令一览（含别名），可直接复制使用：

vercel sandbox list # list sandboxes (alias: ls) vercel sandbox create # create a sandbox vercel sandbox create --connect # create and immediately open a shell vercel sandbox run -- node -e "console.log('hi')" # create + run a command in one step vercel sandbox exec <sandbox-id> -- npm test # execute a command in an existing sandbox vercel sandbox connect <sandbox-id> # interactive shell (aliases: ssh, shell) vercel sandbox copy ./local.txt <sandbox-id>:/tmp/ # copy files (alias: cp) vercel sandbox stop <sandbox-id> # stop one or more sandboxes (aliases: rm, remove) vercel sandbox config network-policy <sandbox-id> --network-policy deny-all # update sandbox network policy vercel sandbox snapshot <sandbox-id> --stop # take a filesystem snapshot (sandbox is stopped) vercel sandbox snapshots list # list snapshots (subcommand group: list/get/delete) vercel sandbox login # log in to the Sandbox CLI vercel sandbox logout # log out of the Sandbox CLI

三、子命令详解

3.1 查看沙箱：sandbox list/ls

列出当前项目作用域下的所有沙箱：

vercel sandbox list # 或使用别名 vercel sandbox ls

返回结果会展示每个沙箱的 ID 与状态，<sandbox-id>供后续exec、connect、copy、stop、snapshot等命令引用。

3.2 创建沙箱：sandbox create与--connect

创建新的沙箱环境：

vercel sandbox create

若希望创建后立即进入交互式 Shell，追加--connect：

vercel sandbox create --connect

这也是sandboxCommand在 command.ts 中给出的两个官方示例之一。创建动作会启动外部计算资源，执行前请确认意图（见第六节安全提醒）。

3.3 一步完成"创建 + 执行"：sandbox run -- <command>

run把"创建沙箱"和"在其中执行命令"合并为一步，适合一次性任务：

vercel sandbox run -- node -e "console.log('hi')"

--之后的内容会作为命令原样转发给沙箱进程执行，无需先手动create再exec。

3.4 在已有沙箱中执行命令：sandbox exec <sandbox-id> -- <command>

对已存在的沙箱执行命令，典型场景是在 CI 中跑测试：

vercel sandbox exec <sandbox-id> -- npm test

注意：exec要求目标沙箱处于运行状态，若目标已被stop则需要先重新创建。

3.5 交互式 Shell：sandbox connect <sandbox-id>（别名ssh/shell）

以交互方式连接一个沙箱，进入其 Shell：

vercel sandbox connect <sandbox-id> # 别名 vercel sandbox ssh <sandbox-id> vercel sandbox shell <sandbox-id>

交互式会话期间，本地终端会直接对接沙箱的 stdin/stdout，适合调试与排查。连接会话会占用外部计算资源，结束使用后请及时stop。

3.6 文件复制：sandbox copy/cp

将本地文件复制进沙箱（目标路径需以沙箱 ID 和冒号开头）：

vercel sandbox copy ./local.txt <sandbox-id>:/tmp/

cp为copy的别名。该命令支持本地路径到沙箱路径的映射，便于把测试数据、配置或二进制注入沙箱环境。

3.7 停止沙箱：sandbox stop/rm/remove

停止一个或多个沙箱以释放外部计算资源：

vercel sandbox stop <sandbox-id> # 可一次停止多个 vercel sandbox stop <sandbox-id-1> <sandbox-id-2> # 别名 vercel sandbox rm <sandbox-id> vercel sandbox remove <sandbox-id>

stop是回收资源的主要手段，也是snapshot流程的前置条件（见 3.9）。

3.8 网络策略配置：sandbox config network-policy

sandbox config是一个子命令组（subcommand group），当前唯一可配置的项是network-policy：

vercel sandbox config network-policy <sandbox-id> --network-policy deny-all

例如将沙箱网络策略设为deny-all以禁止出网访问，适合在不可信代码或隔离测试场景中收紧网络边界。可用的策略值以vercel sandbox config --help输出为准。

3.9 文件系统快照：sandbox snapshot <sandbox-id> --stop

对沙箱文件系统拍摄快照，用于保存当前环境状态：

vercel sandbox snapshot <sandbox-id> --stop

--stop是必需参数：快照操作会先停止沙箱再拍摄，因此无需（也不应）省略该标志。快照成功后，沙箱处于已停止状态。

3.10 快照管理：sandbox snapshots list / get / delete

sandbox snapshots（复数）是另一个独立的子命令组，与snapshot（单数，负责拍摄）职责分离，专门管理已存在的快照：

vercel sandbox snapshots list # 列出全部快照 vercel sandbox snapshots get # 获取某个快照详情 vercel sandbox snapshots delete # 删除某个快照

3.11 认证管理：sandbox login/sandbox logout

分别用于登录、登出 Sandbox CLI：

vercel sandbox login vercel sandbox logout

登录态独立于 Vercel CLI 自身的会话，但二者在令牌层面存在转发关系，详见第五节。

四、--参数分隔约定：沙箱命令与转发参数的分界线

在run、exec等子命令中，--用于分隔沙箱子命令与要转发给沙箱进程的参数：

vercel sandbox run -- node -e "console.log('hi')" vercel sandbox exec <sandbox-id> -- npm test

--之后的所有内容（如node -e "..."、npm test）不再被vercel sandbox解析，而是原样交给沙箱进程执行。这是编写可复现沙箱命令的关键约定，缺失--可能导致参数被误解析为沙箱 CLI 自身的选项。

五、认证转发与令牌映射

5.1 全局 Flags 转发

Vercel 全局认证相关的三个 flags 会被转发给 Sandbox CLI：

• --scope/-S：设置团队上下文
• --team/-T：--scope的别名（在新命令中不推荐使用）
• --token/-t：认证令牌

从源码看，转发逻辑位于 index.ts：命令先解析--scope、--team、--token，再构造forwardedArgs传给 Sandbox CLI；其中--scope的优先级高于--team（scope ? ['--scope', scope] : team ? ['--team', team] : []）。全局 flag 的完整语义可参考 global-options.md。

5.2 令牌优先级链与VERCEL_TOKEN→VERCEL_AUTH_TOKEN映射

Sandbox CLI 读取的是VERCEL_AUTH_TOKEN环境变量。在自动化（CI / Agent）场景下，推荐直接设置VERCEL_TOKEN，Vercel CLI 会自动将其映射为VERCEL_AUTH_TOKEN供 Sandbox 使用：

export VERCEL_TOKEN=your_token_here vercel sandbox list

结合 index.ts 的实现，令牌的完整优先级链为：

1. 命令行显式传入的--token参数（最高优先级）；
2. 环境中已存在的VERCEL_AUTH_TOKEN；
3. 环境变量VERCEL_TOKEN（自动化首选）；
4. client.authConfig.token（Vercel CLI 本地登录凭据，兜底）。

此外，源码还在转发前执行process.chdir(client.cwd)（index.ts），确保沙箱操作始终在用户指定的项目目录上下文中进行；命令结束后在finally块中恢复原始工作目录与原始的VERCEL_AUTH_TOKEN，避免污染调用方环境（index.ts）。

六、源码级实现解析：转发链路如何工作

vercel sandbox的实现可概括为"参数解析 → 令牌注入 → 动态加载 → 委托执行"四步：

1. 参数解析：getFlagValue()（index.ts）遍历参数数组，既支持--scope <value>形式，也支持--scope=<value>内联赋值形式；
2. 令牌注入：按第五节的优先级链将最终令牌写入process.env.VERCEL_AUTH_TOKEN；
3. 动态加载：通过await import('sandbox')按需加载 Sandbox CLI 模块（对应 package.json 中的sandbox@3.4.0依赖），并以appName: 'vercel sandbox'、withoutAuth: false创建应用实例——withoutAuth: false意味着认证流程默认启用；
4. 委托执行：调用createApp(...).run(forwardedArgs)将剩余参数（含--之后的内容）原样交给 Sandbox CLI 执行；成功返回 0，异常经printError输出后返回 1。

命令的注册面也很清晰：定义在 commands/sandbox/command.ts，导入于 commands/index.ts，批量导出于 commands-bulk.ts，帮助文本sandbox Interact with Vercel Sandbox出现在 help.ts。在 index.ts 处还专门对targetCommand !== 'sandbox'做了分支处理，确保sandbox走独立的动态加载路径。

七、使用注意事项与安全提醒

沙箱命令可能创建外部计算资源（external compute）或交互式会话（interactive sessions），因此在创建（create/run）或连接（connect）沙箱之前，务必先向用户确认意图，避免在不知情的情况下产生外部资源开销。

实践建议汇总：

• 一次性任务优先用run -- <cmd>，省去手动create+exec两步；
• 需要复用的长期环境用create --connect或connect，任务完成后及时stop回收资源；
• 需要保留环境状态时，先snapshot <id> --stop生成快照，再用snapshots list/get/delete管理快照生命周期；
• 收紧网络边界用config network-policy <id> --network-policy deny-all；
• 自动化脚本中统一通过VERCEL_TOKEN注入令牌，避免在 shell 历史中泄露--token。

按照本文的命令速查表与参数约定，即可在终端中完成从创建、执行、文件复制到快照与回收的完整沙箱工作流，并与 Vercel CLI 现有的--scope/--token认证体系无缝衔接。

• CLI
• 后端
• 云原生