Vercel CLI 快速上手安装、登录、项目链接与本地开发完整指南【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel导读本文基于 getting-started.md 整理而成面向希望用 Vercel CLIvercel/vc完成开发 → 预览 → 发布全流程的开发者尤其是需要在 CI、Agent 等非交互环境中自动化操作的用户。你将掌握 CLI 的全局安装与首次登录认证、两种项目链接方式单项目vercel link与仓库级vercel link --repo的选择依据、.vercel/目录内部文件的作用、vercel pull拉取环境数据的正确姿势以及vercel dev/vercel --prod完成本地开发与生产部署的完整命令链路同时会结合当前仓库的 CLI 源码位于 packages/cli深入说明项目解析的底层逻辑帮助你在多项目 Monorepo 中避免最常见的链错项目问题。一、安装 Vercel CLI全局安装 Vercel CLI 只需要一条 npm 命令npm i -g vercel安装完成后命令行中既可以使用vercel也可以使用其缩写vc。所有命令都支持vercel command --help查看完整参数说明——SKILL.md 明确指出对于新增或冷门的 flag已安装 CLI 的--help输出才是最终的事实来源见 SKILL.md因此遇到不确定的选项时优先查询帮助而非猜测。CLI 命令的输入输出约定值得提前注意stdout命令的输出结果如部署 URL、JSON 数据只从标准输出读取stderr警告、进度条与--help文本输出到标准错误流在 Agent / 非交互模式下许多命令会把错误和待确认事项以单个 JSON 对象的形式输出到 stdout其中包含status、reason、hint、next可直接执行的后续命令四个字段。这一约定贯穿后续所有章节尤其是在脚本中捕获部署 URL 时非常关键。二、首次设置认证 → 链接 → 校验 → 拉取 → 开发部署首次使用 CLI 的完整流程可以概括为五个步骤每一步都有明确的命令与目的1. 认证Authenticatevercel loginvercel login会打开浏览器/设备device flow进行认证。两个重要注意点交互环境当浏览器流程启动后需要等待用户主动完成认证不要打断或重试CI / 自动化环境不要使用--token参数token 会出现在进程列表中造成泄露而是通过VERCEL_TOKEN环境变量提供凭证。在 ci-automation.md 中同样强调使用VERCEL_TOKEN环境变量而非--token如果 token 可访问多个团队还需配合--scope指定目标团队。从源码看VERCEL_TOKEN是 CLI 全局支持的凭证来源之一在 client.ts 中统一处理与--token、本地凭据存储属于并列的认证通道。2. 链接项目Link your project链接操作把本地目录与 Vercel 平台上的 Project 建立映射关系二选一vercel link # 单项目为当前工作目录创建映射 vercel link --repo # 仓库级为整个 Git 仓库建立多项目映射Monorepo 场景两种方式都会在项目下创建.vercel/目录。对于包含多个项目的 Monorepo务必使用vercel link --repovercel link只会写入一个project.json只跟踪单个项目见 SKILL.md 中的反模式说明。从 link/command.ts 可以看到link命令还支持以下常用参数参数说明--repo/-r从 Git 仓库链接多个项目alpha 功能--project name-or-id/-p指定要链接的项目名或 ID非交互式链接已有项目时必填--team team-id-or-slug指定团队与--project搭配用于非交互链接--yes跳过提问使用默认团队与设置--cwd path指定要链接的目录link add向已有的仓库链接repo.json追加更多项目典型场景在 CI 或 Agent 环境中自动链接已有项目可写成vercel link --yes --team team-id --project project-name-or-id。3. 校验目标Verify the target链接之后、执行任何有实际影响的操作之前从目标工作目录运行vercel project inspect --non-interactive并确认输出中的 Owner所属用户/团队与 Project 名称与预期一致。校验时需要注意遇到link_required或目标不匹配时立即停止而不是自动执行链接vercel whoami --format json只标识当前认证用户和生效团队并不能验证已链接的项目不要用它替代项目校验SKILL.md 将其列为反模式只读的检查命令如 inspect也可能触发登录或团队 SAML 重新认证进而打开浏览器/设备流程并等待批准——此时应请用户主动完成流程后再继续不要盲目重试。从 inspect.ts 的源码可以看到vercel project inspect会输出项目 ID、名称、Owner、创建时间、Root Directory、Node.js 版本以及 Framework 预设、Build/Output/Install 命令等完整信息是校验链接结果最直接的命令。4. 拉取本地数据Pull local datavercel pullvercel pull会把项目设置与环境数据写入.vercel/目录下包括.vercel/.env.environment.local。如果需要把环境变量写入项目根目录下已被版本控制忽略的.env.local或其它文件名使用vercel env pull从 env/pull.ts 的源码可知env pull默认文件名为.env.local当写入.env.local时还会自动把它追加到.gitignore见该文件 140 行与 393-394 行附近的逻辑避免敏感环境变量被提交进版本库。5. 开发或部署Dev or deployvercel dev # 启动本地开发服务器 vercel --prod # 部署到生产环境vercel dev提供本地开发体验vercel --prod直接发布生产部署。完整的快速开始链路在 SKILL.md 中有汇总login → link / link --repo → pull → dev / deploy → --prod。三、项目链接的解析优先级深入理解.vercel/内部机制项目解析从命令的工作目录cwd开始遵循明确的优先级规则这也是最容易踩坑的地方1.cwd/.vercel/project.json工作目录级链接优先级最高由vercel link创建只针对当前工作目录生效。根目录的单项目链接一般不会被任意子目录继承——也就是说在 Monorepo 的某个子包目录里运行命令时仓库根目录下的project.json不会自动生效。从 projects/link.ts 的源码看project.json采用 AJV 校验必须包含projectId和orgId两个必填字段非空字符串可选字段为projectName解析逻辑getProjectLink()明确优先采用显式的目录级链接.vercel/project.json而非仓库级链接.vercel/repo.json。链接成功后还会生成.vercel/README.txt并向.gitignore追加.vercel/见 projects/link.ts 的linkFolderToProject()。2.repo-root/.vercel/repo.json仓库级链接由vercel link --repo创建记录了 Git 远程名称与一组项目映射。CLI 会选择包含当前工作目录的、目录层级最深的那个已配置项目来匹配。源码中的匹配逻辑位于 util/link/repo.tsfindProjectsFromPath()把项目按directory的路径深度排序sortByDirectory按/分段数量降序优先命中最具体的目录directory .表示项目没有 Root Directory 设置任意路径都算匹配。而getProjectLinkFromRepoLink()在非交互模式下如果候选项目恰好只有一个就直接选中它有多个候选时才返回未解析状态。repo.json的数据结构对应RepoProjectsConfig接口见 util/link/repo.ts{ remoteName: origin, projects: [ { id: prj_xxx, name: web, directory: apps/web, orgId: team_xxx }, { id: prj_yyy, name: api, directory: apps/api, orgId: team_xxx } ] }其中顶层orgId已标记为废弃仅用于兼容旧版repo.json优先读取每个 project 条目上的orgId。仓库根的定位由findRepoRoot()完成先沿目录树向上查找.vercel/repo.json再回退到git rev-parse --show-toplevel能正确处理常规仓库、worktree 与 submodule最后才回退到沿目录树查找.git。3. 未匹配到任何仓库目录交互模式会弹出提示让用户从已配置的项目中选择非交互模式当前行为是——只有一个已配置项目时直接选中它存在多个项目时保持未解析。随后负责创建项目的命令可能进入链接流程。因此非交互模式并不总是失败即停止fail-closed这也是为什么要显式执行vercel project inspect --non-interactive来做校验。4. 重要推论位于某个应用子目录中并不能证明该项目被选中只有当仓库映射覆盖该目录时才成立。在操作项目前务必用vercel project inspect --non-interactive确认解析结果尤其当 repo 映射没有覆盖当前目录时。除了文件链接源码还支持一种环境变量链接方式当同时设置VERCEL_ORG_ID与VERCEL_PROJECT_ID时getLinkedProject()会直接采用这两个环境变量构造项目上下文projects/link.ts如果只设置了其中一个CLI 会报错提示必须两个一起设置。这为 CI 场景提供了第三种选择。四、与 CI / Agent 环境结合的实践要点getting-started 中非交互相关要求在实际自动化场景中的落地要点如下认证用环境变量VERCEL_TOKEN代替--token多团队 token 加--scope显式传--non-interactiveCLI 检测到 Agent 时默认加--non-interactive但普通 CI 不会——必须显式传入需要确认的命令再加--yes先链接再校验Monorepo 中先执行vercel link --repo --yes再用vercel project inspect --non-interactive确认 owner 与 project发生错误先查.vercel/project.json与repo.json的混淆是最常见的失败原因见 ci-automation.md 的 Key Rules。五、从快速上手到完整工作流本文覆盖了 getting-started.md 的全部核心内容安装、认证、链接、校验、拉取与开发/部署的完整链路以及项目链接解析的底层规则。在此基础上可以根据实际场景继续深入仓库中的对应参考文档本地开发细节local-development.md环境变量管理environment-variables.md部署与重部署deployment.mdCI/CD 自动化ci-automation.mdMonorepo 与 Turborepomonorepos.md全局参数global-options.md完整的命令路由决策树Decision Tree位于 SKILL.md可以帮助你快速定位任意场景对应的参考文档而 CLI 全部命令的源码实现集中在 packages/cli/src/commands需要确认某个命令的确切行为时可以直接查阅对应目录的源码与测试。【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考