企业官网建设流程全解析

• CLI
• 后端
• 云原生

vercel pull是 Vercel CLI 中用于将云端项目的最新设置（Project Settings）与环境变量（Environment Variables）同步到本地工作区的核心命令。本文以仓库内评估用例 packages/cli/evals/evals/pull/PROMPT.md 为引子，结合命令实现源码与评估断言，系统讲解vercel pull的全部参数、执行流程、产出文件格式及其在 CLI 自动化评估（Evals）中的验证方式。读完本文，你将能熟练使用vercel pull完成本地环境初始化，并理解其底层实现原理。

一、评估用例背后的命令：一条 Prompt 定义的功能边界

在 Vercel CLI 的 Evals 评估体系中，每个用例（Eval Fixture）由三个文件组成：PROMPT.md（给 Agent 的任务描述）、EVAL.ts（断言测试）和package.json（依赖声明）。pull用例的 PROMPT 全文只有一句话：

Pull the latest project settings and environment variables for this linked project.

（为已链接的项目拉取最新的项目设置与环境变量。）

这句话精炼地概括了vercel pull命令的全部职责——两个动作、一个前提：

• 前提：项目必须已经链接（linked）到 Vercel；
• 动作一：拉取项目设置（Project Settings），写入本地.vercel/project.json；
• 动作二：拉取环境变量（Environment Variables），写入.vercel/.env.<environment>.local。

配套的 EVAL.ts 用两组断言把这条 Prompt 变成了可自动验证的验收标准：

test('agent used vercel pull', () => { const commands = getShellCommands(); const pullCommands = commands.filter(command => /\b(vercel|vc)\s+pull\b/.test(command) ); expect(pullCommands.length).toBeGreaterThan(0); expect( pullCommands.some( command => command.includes('--yes') || /\s-y(\s|$)/.test(command) || command.includes('--environment') ) ).toBe(true); }); test('project settings and environment file were pulled', () => { expect(existsSync('.vercel/project.json')).toBe(true); expect(existsSync('.vercel/.env.development.local')).toBe(true); });

从源码结构看，这套断言从两个维度约束 Agent 的行为：其一，Agent 必须实际执行vercel pull（或vc pull）命令，并且带上--yes/-y（跳过交互确认）或--environment（指定环境）等非交互化参数；其二，命令执行后必须产生两个可验证的产物文件——.vercel/project.json与.vercel/.env.development.local。这两类断言恰好对应了命令的两个核心输出，构成了本文展开的主线。

二、vercel pull命令的完整用法与参数说明

命令定义位于 packages/cli/src/commands/pull/command.ts。从源码（第 7–71 行）可以看出该命令的完整规格：

vercel pull [project-path] [options]

2.1 位置参数

2.2 选项参数

2.3 官方示例（源自 command.ts 第 49–70 行）

# 从云端拉取最新的环境变量与项目设置 vercel pull # 指定目标目录 vercel pull ./path-to-project # 拉取指定环境 vercel pull --environment=production # 拉取 preview 环境中指定 feature 分支的变量覆盖 vercel pull --environment=preview --git-branch=feature-branch

一个值得注意的设计细节（command.ts 第 67 行）：如果只想把环境变量下载到任意指定文件（例如项目根目录的.env.local），官方明确建议改用vercel env pull，因为vercel pull对环境变量文件的落盘位置是有约定的（见下文第四部分）。

三、执行流程：从链接确认到双产物落盘

vercel pull的核心逻辑位于 packages/cli/src/commands/pull/index.ts 的pullCommandLogic函数（第 118–174 行）。其执行流程可概括为四个阶段：

阶段一：确保项目链接（ensureLink）命令首先调用ensureLink('pull', client, cwd, ...)确认当前目录已链接到 Vercel 项目。通过--project传入项目名时，会以failIfNotFound: true强制要求项目存在；否则若未链接，命令会引导用户完成链接（vercel link）。这里使用pullEnv: false表示链接阶段本身不拉取环境变量。

阶段二：解析目标目录如果当前目录位于某个 Git 仓库中（存在仓库级链接），repoRoot会被解析出来，目标目录为join(repoRoot, project.rootDirectory || '')，即仓库根目录加上云端项目配置的rootDirectory；否则目标目录就是当前工作目录。这一步保证了拉取产物能落到与云端配置一致的位置。

阶段三：拉取环境变量调用pullAllEnvFiles（第 27–48 行），把指定环境的环境变量写入.vercel/.env.<environment>.local。例如默认环境下为.vercel/.env.development.local，这正是评估断言中检查的文件。

阶段四：下载项目设置调用writeProjectSettings(currentDirectory, project, org, isRepoLinked)将项目设置写入.vercel/project.json，并输出Downloaded project settings to ...的成功提示（第 158–171 行）。

此外，命令成功返回且未使用--yes时（index.ts 第 111–113 行），CLI 会调用autoInstallVercelPlugin尝试自动安装 Vercel 插件，为后续的本地开发命令做准备。

四、环境变量拉取的底层实现细节

vercel pull的环境变量部分复用了vercel env pull的底层逻辑envPullCommandLogic（packages/cli/src/commands/env/pull.ts，第 227 行起），只是在文件路径上固定为.vercel/.env.<environment>.local。理解这些细节有助于排查实际使用中的各种行为。

4.1 文件内容与标识头

写入的环境变量文件以固定前缀开头（env/pull.ts 第 40 行）：

# Created by Vercel CLI KEY="value"

该标识头（CONTENTS_PREFIX）在覆盖逻辑中扮演关键角色：如果已存在文件且其内容以该前缀开头，CLI 会直接提示Overwriting existing ... file而无须确认；若文件存在但不是由 Vercel CLI 创建的，则必须通过--yes或交互确认才能覆盖，否则输出Canceled。

4.2 环境与分支覆盖

环境解析由parseTarget完成，默认development。若指定--git-branch，下载时会额外拉取该分支在目标环境上的变量覆盖，下载提示也会变为 "and any overrides for branch "（第 284–289 行）。

4.3 敏感变量的脱敏处理

对于类型为sensitive的环境变量（其值受保护、不可明文回读），拉取后会用占位符[SENSITIVE]替换真实值（第 80、336–339 行）。代码通过getRedactedSensitiveKeys先比对远程记录中值为空的 key 与sensitive类型的 key，再对交集做脱敏，避免把敏感内容泄露进本地文件。

4.4 保留本地私有变量

如果本地已存在.env.<environment>.local文件，合并时会保留"本地存在但云端不存在"的 key（第 340–351 行），但会排除VERCEL_OIDC_TOKEN与三个自动注入的分析 ID（VERCEL_ANALYTICS_ID、VERCEL_SPEED_INSIGHTS_ID、VERCEL_WEB_ANALYTICS_ID，见第 74–78 行的VARIABLES_TO_IGNORE）。保留的 key 会在输出中提示：

Kept LOCAL_ONLY_KEY (defined locally, not found in the development Environment)

最终写入的内容按 key 排序，并对换行符做转义（\n/\r，第 420–425 行），保证单行格式的.env语法有效。

4.5 自动加入 .gitignore

当文件名为.env.local（注意：这是env pull默认名，而vercel pull写入的是.vercel/目录下的文件）时，CLI 会将其加入.gitignore（使用.env*规则，第 391–401 行），防止密钥误提交。.vercel/目录本身同样会通过README.txt与 gitignore 机制得到保护（见 packages/cli/src/util/projects/link.ts 中的VERCEL_DIR_README_CONTENT，第 550–566 行）。

五、项目设置写入：.vercel/project.json的结构

项目设置由 packages/cli/src/util/projects/project-settings.ts 的writeProjectSettings函数（第 27–64 行）写入.vercel/project.json。其 JSON 结构包含两部分：

{ "projectId": "prj_xxxx", "orgId": "team_xxxx", "projectName": "my-app", "settings": { "createdAt": 1700000000000, "framework": "nextjs", "devCommand": null, "installCommand": null, "buildCommand": null, "outputDirectory": null, "rootDirectory": null, "directoryListing": false, "nodeVersion": "20.x", "analyticsId": null } }

几点需要特别注意：

• 仓库级链接的差异：当目录通过 Git 仓库链接时（isRepoLinked为真），projectId、orgId、projectName三个字段会被置为undefined，只写入settings部分（第 43–46 行）。此时 link.ts（第 229–233 行）会把这种"仅设置"的project.json视为无目录级链接，转而通过.vercel/repo.json解析仓库链接——这是多目录 Monorepo 场景下保持链接一致性的关键设计。
• analyticsId的推算：仅当项目启用了 Analytics（存在analytics.id，且未被禁用或已重新启用）时才写入（第 33–41 行）。
• 后续消费方：这份project.json是vercel build、vercel dev等命令读取项目配置的依据（project-settings.ts 第 24–26 行注释明确说明），也是getLinkFromDir验证链接有效性的输入（link.ts 第 211–260 行，使用 AJV 校验 schema，损坏的链接文件会提示删除目录后重新链接）。

六、Evals 如何端到端验证vercel pull

6.1 用例结构

pull用例位于 packages/cli/evals/evals/pull/，遵循"任意包含 PROMPT.md + EVAL.ts + package.json 的目录即视为一个 eval"的递归发现规则（见 packages/cli/evals/README.md）。其package.json仅声明vitest作为测试运行器，依赖极简。

6.2 断言数据来源

EVAL.ts 中的getShellCommands从__agent_eval__/results.json读取 Agent 在沙箱中执行过的全部 shell 命令（第 4–12 行），即"过程"维度；文件系统断言则直接检查工作目录中的产物（第 31–33 行），即"结果"维度。过程 + 结果的双重校验，使得该用例既能确认 Agent 采用了正确的命令与参数，又能确认命令真正生效。

6.3 运行方式

在仓库根目录下，可用以下命令运行相关评估（详见 README 的 Commands 一节）：

# 从 packages/cli 目录运行 cd packages/cli # 预览评估矩阵与发现的用例（无需凭据） pnpm test:evals:dry # 只运行 pull 用例 CLI_EVAL_EVALS=pull pnpm test:evals # 本地生成兼容 dashboard 的 fixture 结果（无需 Agent 与 API） pnpm test:evals:local-fixture

运行真实评估需要AI_GATEWAY_API_KEY以及VERCEL_OIDC_TOKEN或VERCEL_TOKEN。评估沙箱中的 Agent 可以使用本地构建的 CLI（packages/cli/dist/vc.js），通过将packages/cli/dist加入PATH即可让vercel/vc指向本地构建（README 的 "Using Local CLI Build" 一节）。

6.4 与其他用例的关联

pull用例在评估体系中与link（非交互式链接）、env/*（环境变量的 ls/add/pull/update/remove 子命令族）用例相互印证：vercel pull实际是"链接 + 环境变量 + 项目设置"三者的组合操作。若项目未链接，pull 会触发与 link 用例相同的引导流程；环境变量的下载细节则与 env/pull 用例共享同一底层实现。

七、常见问题与最佳实践

Q1：vercel pull与vercel env pull有什么区别？vercel pull一次性拉取环境变量（固定写入.vercel/.env.<environment>.local）和项目设置（.vercel/project.json）；vercel env pull只拉取环境变量，且文件名可自定义（默认.env.local）。需要把变量放到自定义路径时用后者（command.ts 第 67 行注释明确指引）。

Q2：拉取时提示文件已存在怎么办？若目标文件非 Vercel CLI 创建，会要求确认覆盖；自动化场景（CI、Agent）应加--yes（env/pull.ts 第 245–276 行的outputActionRequired分支会给出vercel env pull <file> --yes的建议命令）。

Q3：为什么.vercel/project.json里没有 projectId？因为当前目录是通过 Git 仓库级链接关联的（isRepoLinked 为真），链接信息在.vercel/repo.json中，project.json仅保存设置。若需要目录级链接（每个子目录独立指向项目），需在对应目录单独执行链接。

Q4：敏感变量被写成了[SENSITIVE]？这是刻意的脱敏行为。sensitive类型变量的真实值不会随vercel pull明文下载，需要在部署或运行环境中通过其他安全渠道注入（如vercel env的受保护存储），而不是依赖本地.env文件。

Q5：如何验证拉取是否成功？成功输出会包含Downloaded project settings to .vercel/project.json与Updated/Created .env.development.local file字样；在评估场景中，检查.vercel/project.json与.vercel/.env.development.local两个文件是否存在即可（EVAL.ts 的第二个测试用例正是这样做的）。

八、小结

vercel pull是本地开发工作流中连接云端配置的枢纽命令。通过本文可以看到：在 CLI 内部，它由ensureLink（链接解析）、envPullCommandLogic（环境变量下载）与writeProjectSettings（设置落盘）三段逻辑组合而成；在自动化评估侧，pull用例则以"命令执行 + 产物存在"的双重断言，把这条一行 Prompt 变成了可回归验证的验收标准。无论是手动初始化本地环境，还是为 Agent / CI 构建非交互式拉取流程，掌握本文所述的参数与行为细节都能让你对每一步的产物和副作用了然于胸。

• CLI
• 后端
• 云原生