Vercel CLI

Vercel

开发。预览。发布。

文档 · 更新日志 · 模板 · CLI

Vercel

Vercel 的 AI Cloud 是一个统一的平台，用于构建现代应用，让团队在专注于产品而非基础设施的同时，能够灵活应变、快速行动并确保安全。

部署

通过导入项目、选择模板或使用 Vercel CLI开始使用。然后，执行 git push 进行部署。

原生 CLI 二进制文件

标准的 npm 安装方式保持不变：

npm i -g vercel

原生 CLI 二进制文件单独分发，不会影响 vercel npm 包。若要使用原生二进制文件并替换现有的全局 vercel 和 vc 命令，请显式安装原生包：

npm i -g @vercel/vc-native --force

--force 标志允许 npm 替换现有的全局 vercel 和 vc 可执行文件链接。未安装 @vercel/vc-native 的用户仍会使用通过 npm i -g vercel 安装的常规 Node.js CLI。

如果需要特定二进制文件，也可以直接安装平台专用包：

npm i -g @vercel/vc-native-darwin-x64 --force

文档

如需了解如何使用 Vercel，请参阅我们的文档。

贡献

本项目使用 pnpm 安装依赖并运行脚本。

你可以使用 vercel 脚本运行本地更改，就像调用 Vercel CLI 一样。例如，vercel deploy --cwd=/path/to/project 可以通过 pnpm vercel deploy --cwd=/path/to/project 在本地更改下运行。

为此仓库贡献代码时，请先通过 Vercel Community 与仓库维护者讨论你希望进行的更改，然后再提交 Pull Request。

请阅读我们的行为准则，并在与项目相关的所有互动中遵守该准则。

本地开发

本项目采用单体仓库配置，一个仓库中包含多个 npm 包。依赖项通过 pnpm 而非 npm CLI 安装和管理。

请执行以下操作以开始：

git clone https://github.com/vercel/vercel
cd vercel
corepack enable
pnpm install
pnpm build
pnpm lint
pnpm test-unit

进行更改前，请确保所有测试均通过。

运行 Vercel CLI 更改

你可以在 cli 包中使用 pnpm vercel，通过本地更改调用 Vercel CLI：

cd ./packages/cli
pnpm vercel <cli-commands...>

更多详情请参阅 CLI 本地开发。

验证更改

完成更改后（我们甚至建议在修改过程中就进行验证），请运行以下命令，确保所有测试仍然通过：

pnpm test-unit

请在项目根目录运行。

如果有任何测试失败，请确保一并修复。有关测试运行方式的更多信息，请参阅解读测试错误，尤其是集成测试。

复现受影响的构建和类型检查

CI 会比较 Pull Request 的 head 与 GitHub 记录的 base 和 head 提交。若要在本地检查相同的受影响 Turborepo 任务计划，请先提交更改，检出 Pull Request 的 head，并设置明确的 SCM 范围：

export TURBO_SCM_BASE=$(gh pr view --json baseRefOid --jq .baseRefOid)
export TURBO_SCM_HEAD=$(gh pr view --json headRefOid --jq .headRefOid)
git fetch origin "$TURBO_SCM_BASE" "$TURBO_SCM_HEAD"
test "$(git rev-parse HEAD)" = "$TURBO_SCM_HEAD"
node utils/gen.js
pnpm exec turbo run ci:checks --affected --dry=json

要像 CI 一样执行选定的任务，请将最后一个命令替换为：

pnpm exec turbo run ci:checks --affected --output-logs=errors-only --summarize --continue

两个提交都必须存在于本地克隆中；CI 使用完整历史记录检出，如果缺少提交，会直接失败，而不会将其视为空更改。Lint、格式检查、依赖项检查和生成的资源验证仍会在整个仓库范围内执行。

拉取请求流程

确认更改正常运行后，请在主仓库中发起拉取请求。

维护者会审核拉取请求，我们的持续集成平台也会检查测试。

解读测试错误

此仓库中主要有两类测试：单元测试和端到端（E2E）测试。

单元测试主要使用 Vitest 运行，由于测试的是独立行为，因此执行速度很快。

端到端测试

集成测试会使用 test 项目名称在你的 Vercel 账户中创建部署。每次测试完成部署后，都会使用 probes 键检查响应是否符合预期值。如果值不匹配，你会看到说明差异的消息。如果部署构建失败，你会看到更通用的消息，例如：

[Error: Fetched page https://test-8ashcdlew.vercel.app/root.js does not contain hello Root!. Instead it contains An error occurred with this application.

    NO_STATUS_CODE_FRO Response headers:
       cache-control=s-maxage=0
      connection=close
      content-type=text/plain; charset=utf-8
      date=Wed, 19 Jun 2019 18:01:37 GMT
      server=now
      strict-transport-security=max-age=63072000
      transfer-encoding=chunked
      x-now-id=iad1:hgtzj-1560967297876-44ae12559f95
      x-now-trace=iad1]

在这种情况下，你可以访问失败部署的 URL，并在末尾添加 /_logs 来查看构建错误。以上述情况为例，地址为 https://test-8ashcdlew.vercel.app/_logs

此部署的日志会包含实际错误，有助于你了解问题所在。

在本地运行集成测试

不建议在本地运行完整的集成测试套件，但有时在自己的机器上单独运行失败的测试会很有用。为此，你需要确保在 shell 中配置了相应的凭据：

1. 创建访问令牌。按照此处的说明操作：https://vercel.com/docs/rest-api#creating-an-access-token。确保令牌的范围为你的个人 账户。
2. 从 Vercel 控制面板获取团队 ID：https://vercel.com/<MY-TEAM>/~/settings。
3. 将以下内容写入 shell rc 文件：echo 'export VERCEL_TOKEN=<MY-TOKEN> VERCEL_TEAM_ID=<MY-TEAM-ID>' >> ~/.zshrc

完成后，你应该就能触发集成测试了。选择一个 已隔离的测试来确认一切正常：

cd packages/next

运行测试：

pnpm test test/fixtures/00-server-build/index.test.js

说明

如果获取部署时收到 401 状态码，你需要在项目中停用 Deployment Protection。

@vercel/nft

部分 Builder 会使用 @vercel/nft 在部署前对文件进行树摇。如果你怀疑此树摇机制存在错误，可以在项目中创建以下脚本：

const { nodeFileTrace } = require('@vercel/nft');
nodeFileTrace(['path/to/entrypoint.js'], {
  ts: true,
  mixedModules: true,
})
  .then(o => console.log(o.fileList))
  .then(e => console.error(e));

运行此脚本后，你会看到所有导入的文件。如果有文件缺失，则问题出在 @vercel/nft，而不是 Builder。

使用现有项目部署 Builder

有时你可能想在现有项目中测试 Builder 的更改，例如使用 vercel dev 或实际部署。你可以将 Builder 打包为 tarball 上传，无需每次更改 Builder 都发布到 npm。

1. 切换到所需 Builder 的目录：cd ./packages/node
2. 运行 pnpm build，编译 TypeScript 并执行其他构建步骤
3. 运行 npm pack 创建 tarball 文件。务必不要使用 pnpm pack，因为它不会保留文件权限
4. 将生成的 tarball 移至某个目录
5. 运行 vercel <directory> 上传 tarball 文件并获取 URL。记得在 URL 末尾追加 /<tarball name>
6. 编辑任意现有的 vercel.json 项目，并将 use 替换为该 URL
7. 运行 vercel 或 vercel dev，使用实验性 Builder 进行部署

**注意：**你需要在 settings -> deployment protection 中关闭 Vercel 身份验证，以便下载 Builder。

参考

• 行为准则
• 贡献指南
• Apache 2.0 许可证