Vercel CLIvercel link实战非交互式将本地目录链接到指定团队与项目【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercelvercel link别名vc link是 Vercel CLI 中最基础也最关键的命令之一它把本地目录与 Vercel 云端项目建立绑定关系是后续deploy、pull、env等命令生效的前提。本文以仓库中 link eval 的提示词Link this directory to the target team and project.为主线结合 命令定义、命令实现、链接产物解析 与 eval 断言逻辑系统讲解vercel link的参数体系、非交互执行原理、链接产物.vercel/project.json的结构以及在 CI / Agent 场景下可复现、可验证的链接方式。一、vercel link要解决什么问题Vercel 的项目模型是云端的 Project 本地的目录。要让本地的vercel deploy知道代码该部署到哪个云端项目、所属团队Team是谁就必须先在本地建立一条链接记录。从 链接模块的常量定义 可以看到这条记录存放在本地目录的.vercel/目录下VERCEL_DIR .vercel—— 首选配置目录VERCEL_DIR_FALLBACK .now—— 兼容旧版 CLI 的遗留目录VERCEL_DIR_PROJECT project.json—— 保存目录级链接orgIdprojectIdVERCEL_DIR_REPO repo.json—— 保存仓库级链接vercel link --repo使用。vercel link的官方命令描述就是 Link a local directory to a Vercel projectcommand.ts它做的事正是 PROMPT.md 要求 Agent 完成的任务把当前目录链接到目标团队target team与目标项目target project。二、命令参数全解交互与非交互的完整选项vercel link的命令定义集中在 command.ts其选项是理解整个命令的钥匙选项短参类型说明--repo-rBoolean从当前 Git 仓库链接多个项目alpha 阶段--project-pString指定要链接的项目名或项目 ID非交互式链接已有项目时必填--team—String参数TEAM_ID_OR_SLUG指定团队 ID 或 slug配合--project用于非交互式链接--yes—Boolean跳过提问使用默认团队与默认设置完成链接--confirm—Boolean已废弃等价于--yes该命令还提供link add子命令--repo仓库级链接建立后为已有仓库链接追加项目。命令示例来自 command.ts# 交互式将当前目录链接到一个 Vercel 项目 vercel link # 跳过所有提问使用默认团队与设置 vercel link --yes # CI / Agent 场景链接到指定团队的指定项目非交互、可复现 vercel link --yes --team team-id --project project-name-or-id # 链接指定目录旧语法 vc link directory 已废弃 vercel link --cwd /path/to/project # 仓库级链接alpha vercel link --repo需要注意两个废弃信号index.tsvc link directory位置参数语法已废弃CLI 会给出警告请改用vc link --cwd dir--confirm已废弃CLI 会提示 --confirmis deprecated, please use--yesinstead并把--confirm的值合并到--yes处理。--scope全局参数同样可用在 eval 断言中要求命令形如--scope teamId或--scopeteamId用于把链接操作限定在指定团队范围内详见下文第五节。三、非交互模式Agent 与 CI 场景的正确打开方式3.1 非交互的判定逻辑link 命令实现 中有一段核心逻辑决定命令是否走非交互路径// Non-interactive when flag is passed or when agent (e.g. no TTY) // so JSON is output when confirmation needed const linkNonInteractive client.nonInteractive || client.argv.includes(--non-interactive); const link await ensureLink(link, client, cwd, { autoConfirm: yes, // --yes 生效点 forceDelete: true, // 覆盖已有链接 selectedOrg, // 显式 --scope 解析出的组织 projectName: parsedArgs.flags[--project], successEmoji: success, nonInteractive: linkNonInteractive, pullEnv: false, // link 本身不拉取环境变量 });也就是说只要满足以下任一条件link就以非交互模式运行传入了--non-interactive标志client.nonInteractive为真CLI 检测到当前不是 TTY例如由 Agent 驱动、管道输入等场景传入了--yesautoConfirm: true所有确认问题自动选择默认值。在无 TTY 的 Agent 环境下即使不显式加标志CLI 也会自动进入非交互路径需要确认时直接输出 JSON 结果。3.2 eval 对非交互的强制要求EVAL.ts 中专门有一条测试 agent used vercel link in non-interactive mode先读取__agent_eval__/results.json中o11y.shellCommands记录的全部 shell 命令过滤出匹配\b(vercel|vc)\slink\b的命令断言其中至少一条包含--yes、-y空格分隔或结尾、或--non-interactive之一。这条断言说明在自动化场景中能跑通还不够必须显式给出非交互标志否则 prompt 交互可能挂起、或行为不可复现。这是编写 CI / Agent 脚本时的硬性要求。四、链接产物.vercel/project.json的结构与校验4.1 文件内容与 schema执行成功后CLI 会在项目根目录写入.vercel/project.json。从 projects/link.ts 的 schema 定义 可知其结构{ projectId: prj_xxxxxxxxxxxxxxxxxxxxx, orgId: team_xxxxxxxxxxxxxxxxxxxxx, projectName: my-project }其中projectId与orgId为必填字段长度至少 1projectName为可选的辅助字段。orgId即团队 IDprojectId即云端项目 ID。eval 的元数据校验EVAL.ts会读取evals-setup.json中的teamId/projectId然后断言.vercel/project.json的orgId与projectId完全一致——这验证了链接到了正确的团队与项目而非任意项目。4.2 目录级链接优先于仓库级链接当同时存在.vercel/project.json目录级与.vercel/repo.json仓库级时getProjectLink 会优先采用目录级链接避免新建的本地链接被仓库级链接覆盖而重新弹窗询问。但若调用方显式传入--projectprojectNameIsExplicit为真且本地目录链接的项目与--project不一致则以显式参数为准。4.3.vercel与.now冲突检测getVercelDirectory 会在.vercel与.now同时存在时报错CONFLICTING_CONFIG_DIRECTORIES提示删除.now目录。旧项目迁移时需要注意这一点。五、eval 视角一次完整的链接正确性验证仓库把这条 PROMPT 实现为一个标准 eval fixturepackages/cli/evals/evals/link/由 EVAL.ts 提供四条断言完整定义了链接成功的验收标准链接产物存在L25-L29.vercel/project.json或.vercel/config.json至少存在其一元数据匹配L31-L53若提供evals-setup.json则project.json.orgId必须等于teamId、projectId必须等于projectId非交互执行L55-L73命令中必须出现--yes/-y/--non-interactive作用域正确L75-L94当提供teamId时命令必须包含--scope teamId或--scopeteamId。这四条规则可以原样迁移到你的 CI 脚本设计中先执行非交互link再检查产物与元数据最后把--scope写死在命令里防止误链到错误的团队。eval 运行环境的认证与配置由 setup/auth-and-config.ts 注入把VERCEL_TOKEN写入沙箱的$HOME/.local/share/com.vercel.cli/auth.json与$HOME/.vercel/auth.json并把CLI_EVAL_TEAM_ID默认team_KhlEYrm473sP7ybEytVDlfyj写入config.json的currentTeam同时关闭遥测telemetry.enabled: false。这正是目标团队在 eval 沙箱中的落地方式。六、本地复现与运行 evalslink eval 依托 packages/cli/evals/README.md 描述的轻量 eval 基础设施。每个 eval fixture 由三件套组成PROMPT.mdEVAL.tspackage.jsonrunner 在evals/evals/下递归发现。# 1. 先构建本地 CLIAgent 可直接使用 dist/vc.js无需 npm install cd packages/cli pnpm build # 2. 干跑预览会被执行的 eval 矩阵不需要凭证不发 API 请求 pnpm test:evals:dry # 3. 只跑 link 这一个 eval需要 VERCEL_TOKEN / AI_GATEWAY_API_KEY CLI_EVAL_EVALSlink pnpm test:evals常用环境变量说明环境变量作用CLI_EVAL_EVALS逗号分隔的 fixture 列表如link,non-interactiveCLI_EVAL_EXCLUDE跳过指定 fixture如依赖不可用 marketplace 提供方的CLI_EVAL_AUTH_STATES认证状态矩阵如logged-in,not-logged-inCLI_EVAL_SKILLS_MODESwith-skills/without-skills控制是否注入 CLI skillsCLI_EVAL_PROJECT_MODESlinked-project/no-linked-project控制项目是否预链接CLI_EVAL_TEAM_ID目标团队 IDeval 专用团队eval 系统还支持临时项目模式未设置CLI_EVAL_PROJECT_ID时runner 会为每次 eval 用VERCEL_TOKEN与CLI_EVAL_TEAM_ID创建一次性项目、链接后即删除设置CLI_EVAL_PROJECT_ID则使用固定项目。这与 README.md 中描述的 CI 配置EVAL_TOKEN、EVAL_TEAM_ID、EVAL_PROJECT_ID等 secret对应可在不影响真实项目的前提下反复验证 link 行为。七、实战总结一条可复现的非交互 link 命令综合 PROMPT 目标、命令实现与 eval 断言在 CI / Agent 中链接到指定团队与项目的最小可靠写法是vercel link --yes --team team-id --project project-name-or-id --scope team-id或使用全局等价的短参形式vc link -y --team team-id -p project-name-or-id --scopeteam-id执行后检查cat .vercel/project.json确认orgId等于目标团队 ID、projectId等于目标项目 ID。若本地同时存在旧版.now目录先删除以免触发CONFLICTING_CONFIG_DIRECTORIES错误。此后vercel pull、vercel env pull、vercel deploy等命令都会自动沿用这条链接无需再次交互。【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考