Vercel CLI 非交互式构建实战：`vercel build --yes` 的 Eval 场景与底层实现

• CLI
• 后端
• 云原生

本篇技术指南围绕 Vercel 开源仓库中packages/cli/evals/evals/build/目录下的PROMPT.md任务说明展开，核心主题是在自动化（Agent / CI）环境中以非交互方式完成vercel build构建。你将掌握vercel build --yes/-y/--non-interactive的完整用法、它背后的 Eval 测试断言方式，以及 CLI 构建命令在源码层面的参数解析与自动pull行为，从而在无人值守场景中稳定完成 Vercel 项目构建。

任务文档概述：PROMPT.md 究竟要求什么

关联文档packages/cli/evals/evals/build/PROMPT.md全文共两条指令：

Link this directory to Vercel (if needed) and build it.

Use anon-interactivebuild command so it completes without prompts—e.g.vercel build --yesorvercel build -y.

翻译过来是两件事：

1. 如需要，先把当前目录链接（link）到 Vercel，然后执行构建；
2. 必须使用非交互式构建命令，让命令在没有提示的情况下自动完成，例如vercel build --yes或vercel build -y。

这不是一份泛泛的命令手册，而是 Vercel CLI Eval（评估）体系中名为build的测试夹具（fixture）。它被递归发现并交由@vercel/agent-eval执行，用于验证 AI Agent 是否能在沙箱目录中自主完成「链接 + 构建」任务，并自动选择非交互标志。下面从仓库源码逐步展开这条任务链路的每个环节。

一、Build Eval 夹具的组成与断言逻辑

一个完整的 Eval fixture 由三个文件组成（见packages/cli/evals/README.md中的结构说明，递归发现规则为「任意同时包含PROMPT.md+EVAL.ts+package.json的目录」）：

EVAL.ts 的两个核心断言

packages/cli/evals/evals/build/EVAL.ts中定义了两个测试：

断言一：构建必须真实成功。它检查.vercel/output目录存在，并且该目录下存在config.json或builds.json：

test('build completed successfully', () => { const outputDir = '.vercel/output'; expect(existsSync(outputDir)).toBe(true); expect( existsSync(`${outputDir}/config.json`) || existsSync(`${outputDir}/builds.json`) ).toBe(true); });

这是vercel build成功执行的直接产物证据：CLI 会把构建结果写入.vercel/output，并生成config.json（Build Output API 配置）或builds.json（旧式构建产物清单）。

断言二：Agent 必须使用非交互式标志。它读取__agent_eval__/results.json中由观测层（o11y）记录的 shell 命令，过滤出vercel build/vc build命令，并检查其中是否包含--yes、-y或--non-interactive：

const hasNonInteractive = buildCommands.some(command => { return ( command.includes('--yes') || /\s-y(\s|$)/.test(command) || command.endsWith('-y') || command.includes('--non-interactive') ); }); expect(hasNonInteractive).toBe(true);

注意这里的匹配细节：-y不仅要求出现，还要求是独立参数（前后有空格或位于命令末尾），避免把--yes之类的长参数误判。EVAL.ts顶部注释也明确说明了设计意图："we expect the agent to have run a successful build and to have used a non-interactive flag, as observed from the recorded shell commands."

夹具的其余文件

• packages/cli/evals/evals/build/package.json：一个极简的静态站点包，build脚本仅为echo ok，意味着该 Eval 不依赖真实前端框架，聚焦验证「链接 + 构建 + 非交互」这一 CLI 行为本身；
• packages/cli/evals/evals/build/index.html：一个仅含标题Build Eval的占位 HTML，作为静态站点的入口。

二、为什么必须用非交互式标志：prompt 阻塞的代价

vercel build在本地缺少项目设置或目录尚未链接时，会进入交互式提问（例如询问要链接到哪个团队、哪个项目、是否覆盖现有设置）。在人类终端里这没有问题，但在以下两类场景中会直接卡死：

1. AI Agent / 自动化脚本执行：命令在等待 stdin 输入，而 Agent 不会（也不应）去模拟输入，任务超时失败；
2. CI/CD 流水线：无 TTY 环境下交互提示通常直接导致命令失败。

PROMPT.md特意强调 "so it completes without prompts"，正是要训练 Agent 养成「先想清楚环境是否已就绪，再用非交互标志兜底」的习惯。同仓库的non-interactiveEval（指令为 "Link this directory to the Vercel team and project using the Vercel CLI."）则从vercel link的角度验证了同样的原则，其EVAL.ts断言.vercel/project.json或.vercel/config.json已生成，且链接命令同样使用了--yes/-y/--non-interactive。两个 Eval 相互印证：从link到build，非交互是自动化场景的标配行为。

三、源码级原理：vercel build如何响应--yes

3.1 标志的注册

packages/cli/src/commands/build/command.ts中，build命令复用了通用选项projectOption与yesOption：

import { projectOption, yesOption } from '../../util/arg-common'; // ... ...yesOption,

yesOption定义了--yes（等价-y）标志，作用是"跳过确认提示"。

3.2 标志的读取与追踪

packages/cli/src/commands/build/index.ts中：

telemetryClient.trackCliFlagYes(parsedArgs.flags['--yes']); // ... const yes = Boolean(parsedArgs.flags['--yes']);

CLI 将--yes解析为布尔值并参与后续决策；同时它还会被上报到遥测，用于统计该标志的使用情况（trackCliFlagYes）。

3.3 无项目设置时的自动 pull

构建命令在本地缺少项目设置时，行为取决于是否携带--yes。源码中的提示信息揭示了完整逻辑（packages/cli/src/commands/build/index.ts）：

'No project settings found locally. Run pull to retrieve them, or re-run with --yes to pull automatically.'

即：无--yes时，命令提示开发者手动执行vercel pull --yes --environment <target>来获取项目设置；带--yes时，build会自动完成pull，将项目设置（.vercel/project.json、环境变量等）拉取到本地后继续构建。这正是PROMPT.md中 "Link this directory to Vercel (if needed)" 的自动化实现——目录未链接时，--yes会驱动 CLI 自动建立链接与设置。

3.4 非交互模式的认证要求

同一段源码还指出：

'pull --yes' // ... 'In non-interactive mode, set VERCEL_TOKEN for authentication.'

在非交互/无 TTY 环境下，CLI 无法弹出浏览器登录，因此必须预先设置VERCEL_TOKEN（长期访问令牌）来完成认证。这也是运行 Eval 的必要前提之一——packages/cli/evals/README.md明确要求提供VERCEL_TOKEN或VERCEL_OIDC_TOKEN。

四、把 Build Eval 跑起来：Eval Runner 全流程

4.1 运行入口与三条命令

Eval 由packages/cli/evals/run.ts驱动，在packages/cli/目录下有三条常用命令（见 README）：

# 1. 预演：只打印将运行哪些 eval，不产生 API 调用、不需要凭据 pnpm test:evals:dry # 2. 本地夹具：生成 dashboard 可读取的结果形状，不运行 Agent pnpm test:evals:local-fixture # 3. 真实运行：需要 AI_GATEWAY_API_KEY 与 VERCEL_TOKEN / VERCEL_OIDC_TOKEN pnpm test:evals

4.2 递归发现与子集选择

run.ts中的discoverEvals()递归扫描packages/cli/evals/evals/，命中「PROMPT.md+EVAL.ts+package.json三者齐备」的目录即登记为一个 eval。若一个都没找到则直接退出码 0，否则调用@vercel/agent-eval。

只跑build这一个 eval 时：

cd packages/cli CLI_EVAL_EVALS=build pnpm test:evals

环境变量CLI_EVAL_EVALS（逗号分隔列表）用于筛选，CLI_EVAL_EXCLUDE用于排除（例如跳过需要 marketplace 资源的 fixture）。run.ts中的selectEvals()会先取交集再过滤排除项。

4.3 OIDC 令牌填充与变体矩阵

真实运行时，run.ts会先在sandbox-project目录执行vc env pull -y来尝试填充 OIDC 令牌；若失败且存在VERCEL_TOKEN，则降级使用令牌模式并只运行cli实验。随后 runner 会构建「项目模式 × 技能模式 × 认证状态」的变体矩阵，逐变体执行 setup hooks →npx --yes @vercel/agent-eval@latest→ destroy hooks（清理临时项目）。README 还提到，若未设置CLI_EVAL_PROJECT_ID，runner 会为每次运行创建临时项目、链接沙箱并在结束后删除。

4.4 凭据要求

运行真实 Eval 需要（packages/cli/evals/README.md的 "Getting credentials" 一节）：

五、实践建议：在自动化环境中正确使用非交互构建

综合上述文档与源码，可以总结出在 Agent 或 CI 场景下执行vercel build的推荐姿势：

1. 首选长标志并显式化：vercel build --yes。相比-y，长标志在日志与审计中可读性更强；如果环境变量里已配置好令牌与项目设置，它不会产生任何交互。
2. 目录未链接时不必手动vercel link：--yes会驱动 CLI 自动完成必要的链接与pull（对应PROMPT.md中 "Link this directory to Vercel (if needed)"）。若希望更可控，也可先显式执行vercel link --yes，再执行vercel build --yes。
3. 确保认证先行：非交互模式下 CLI 无法弹浏览器，务必预先设置VERCEL_TOKEN（或使用 OIDC），否则命令会因无法认证而失败。
4. 用输出目录验证结果：构建成功后检查.vercel/output下是否生成了config.json或builds.json——这与EVAL.ts的断言一致，可作为 CI 中断言构建产物的标准方式。
5. 本地预演再跑真实 Eval：先pnpm test:evals:dry确认夹具发现与变体矩阵符合预期，再设置凭据执行CLI_EVAL_EVALS=build pnpm test:evals。

结语

packages/cli/evals/evals/build/PROMPT.md虽然只有两句话，却完整定义了一个可自动验证的端到端场景：链接 → 非交互构建 → 产物断言。配合 EVAL.ts 的 Vitest 断言、run.ts 的 runner 逻辑以及build命令源码 对--yes的处理，你可以把这条链路直接迁移到自己的自动化流程中：以vercel build --yes作为无人值守构建的标准命令，以.vercel/output的config.json/builds.json作为成功判据，让 Agent 与 CI 都能稳定、可观测地完成 Vercel 项目构建。

• CLI
• 后端
• 云原生