vercel-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vercel CLI Skill

The Vercel CLI (

vercel

vc

) deploys, manages, and develops projects on the Vercel platform from the command line. Use

vercel <command> -h

for full flag details on any command.

Vercel CLI（

vercel

或

vc

）可通过命令行在Vercel平台上部署、管理和开发项目。使用

vercel <command> -h

查看任意命令的完整参数详情。

Critical: Project Linking

关键：项目关联

Commands must be run from the directory containing the

.vercel

folder (or a subdirectory of it). How

.vercel

gets set up depends on your project structure:

.vercel/project.json
: Created by
```
vercel link
```
. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project.
.vercel/repo.json
: Created by
```
vercel link --repo
```
. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g.,
```
apps/web
```
).

Running from a project subdirectory (e.g.,

apps/web/

) skips the "which project?" prompt since it's unambiguous.

When something goes wrong, check how things are linked first — look at what's in

.vercel/

and whether it's

project.json

repo.json

. Also verify you're on the right team with

vercel whoami

— linking while on the wrong team is a common mistake.

命令必须在包含

.vercel

.vercel

的设置方式取决于你的项目结构：

.vercel/project.json
：由
```
vercel link
```
创建。关联单个项目。适用于单项目仓库，若单仓库中只有一个项目，也可用于多项目仓库（monorepo）。
.vercel/repo.json
：由
```
vercel link --repo
```
创建。关联可能包含多个项目的仓库。当任何项目位于非根目录（如
```
apps/web
```
）时，建议使用此方式。

从项目子目录（如

apps/web/

）运行命令时，会跳过“选择哪个项目？”的提示，因为目标明确。

出现问题时，首先检查关联方式——查看

.vercel/

目录下的内容是

project.json

还是

repo.json

。同时使用

vercel whoami

确认你是否在正确的团队中——关联时选错团队是常见错误。

Quick Start

快速开始

bash

npm i -g vercel
vercel login
vercel link              # single project

bash

npm i -g vercel
vercel login
vercel link              # 单项目

OR

或

vercel link --repo # monorepo vercel pull vercel dev # local development vercel deploy # preview deployment vercel --prod # production deployment

undefined

vercel link --repo # 多项目仓库 vercel pull vercel dev # 本地开发 vercel deploy # 预览部署 vercel --prod # 生产环境部署

undefined

Decision Tree

决策树

Use this to route to the correct reference file:

Deploy →
```
references/deployment.md
```
Local development →
```
references/local-development.md
```
Environment variables →
```
references/environment-variables.md
```
CI/CD automation →
```
references/ci-automation.md
```
Domains or DNS →
```
references/domains-and-dns.md
```
Projects or teams →
```
references/projects-and-teams.md
```
Logs, debugging, or accessing preview deploys →
```
references/monitoring-and-debugging.md
```
Blob storage →
```
references/storage.md
```
Integrations (databases, storage, etc.) →
```
references/integrations.md
```

Access a preview deployment → use

vercel curl

(see

references/monitoring-and-debugging.md

)

CLI doesn't have a command for it → use
```
vercel api
```
as a fallback (see
```
references/advanced.md
```
)
Advanced (API, webhooks) →
```
references/advanced.md
```
Global flags →
```
references/global-options.md
```
First-time setup →
```
references/getting-started.md
```

使用以下指引找到对应的参考文档：

部署 →
```
references/deployment.md
```
本地开发 →
```
references/local-development.md
```
环境变量 →
```
references/environment-variables.md
```
CI/CD自动化 →
```
references/ci-automation.md
```
域名或DNS →
```
references/domains-and-dns.md
```
项目或团队 →
```
references/projects-and-teams.md
```
日志、调试或访问预览部署 →
```
references/monitoring-and-debugging.md
```
Blob存储 →
```
references/storage.md
```
集成（数据库、存储等） →
```
references/integrations.md
```

访问预览部署 → 使用

vercel curl

（详见

references/monitoring-and-debugging.md

）

CLI无对应命令 → 使用
```
vercel api
```
作为替代方案（详见
```
references/advanced.md
```
）
高级功能（API、Webhooks） →
```
references/advanced.md
```
全局参数 →
```
references/global-options.md
```
首次设置 →
```
references/getting-started.md
```

Anti-Patterns

反模式

Wrong link type in monorepos with multiple projects:
```
vercel link
```
creates
```
project.json
```
, which only tracks one project. Use
```
vercel link --repo
```
instead. When things break, check
```
.vercel/
```
first.
Letting commands auto-link in monorepos: Many commands implicitly run
```
vercel link
```
if
```
.vercel/
```
doesn't exist. This creates
```
project.json
```
, which may be wrong. Run
```
vercel link
```
(or
```
--repo
```
) explicitly first.
Linking while on the wrong team: Use
```
vercel whoami
```
to check,
```
vercel teams switch
```
to change.
Forgetting
--yes
in CI: Required to skip interactive prompts.
Using
vercel deploy
after
vercel build
without
--prebuilt
: The build output is ignored.
Hardcoding tokens in flags: Use
```
VERCEL_TOKEN
```
env var instead of
```
--token
```
.
Disabling deployment protection: Use
```
vercel curl
```
instead to access preview deploys.

多项目仓库中使用错误的关联类型：
```
vercel link
```
会创建
```
project.json
```
，仅能跟踪单个项目。应改用
```
vercel link --repo
```
。出现问题时，先检查
```
.vercel/
```
目录。
在多项目仓库中让命令自动关联：若
```
.vercel/
```
不存在，许多命令会隐式运行
```
vercel link
```
，这会创建可能不符合需求的
```
project.json
```
。请先显式运行
```
vercel link
```
（或
```
--repo
```
）。
关联时选错团队：使用
```
vercel whoami
```
检查当前团队，使用
```
vercel teams switch
```
切换团队。
在CI中忘记添加
--yes
：需要此参数跳过交互式提示。
运行
vercel build
后使用
vercel deploy
却未加
--prebuilt
：构建产物会被忽略。
在参数中硬编码令牌：应使用
```
VERCEL_TOKEN
```
环境变量替代
```
--token
```
参数。
禁用部署保护：应使用
```
vercel curl
```
访问预览部署。