vercel-cli-with-tokens

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vercel CLI with Tokens

基于令牌的Vercel CLI使用方法

Deploy and manage projects on Vercel using the CLI with token-based authentication. Use this skill when you have a Vercel access token and need to operate without interactive login.

使用CLI通过基于令牌的身份验证在Vercel上部署和管理项目。当你拥有Vercel访问令牌且需要无需交互式登录进行操作时，可使用此方法。

Authentication

身份验证

Never run
vercel login
. Always use token-based auth via the

--token

flag or

VERCEL_TOKEN

environment variable. This ensures the correct account is used even if another Vercel account is logged in locally.

bash

vercel <command> --token "$VERCEL_TOKEN"

切勿运行
vercel login
命令。请始终通过

--token

参数或

VERCEL_TOKEN

环境变量使用基于令牌的身份验证。这样即使本地已登录其他Vercel账户，也能确保使用正确的账户进行操作。

bash

vercel <command> --token "$VERCEL_TOKEN"

Scoping to a Team

指定团队

Use

--scope

to target a specific team. Accepts a team slug or team ID (

team_...

bash

vercel <command> --token "$VERCEL_TOKEN" --scope <team-slug-or-id>

Not required if the project is already linked (

.vercel/project.json

provides the org context) or if

VERCEL_ORG_ID

is set.

使用

--scope

参数定位到特定团队。支持传入团队别名或团队ID（格式为

team_...

）：

bash

vercel <command> --token "$VERCEL_TOKEN" --scope <team-slug-or-id>

如果项目已关联（

.vercel/project.json

文件中包含组织上下文）或已设置

VERCEL_ORG_ID

环境变量，则无需此参数。

Targeting a Project

指定项目

Use

--project

to target a specific project without needing
vercel link
. Accepts a project name or project ID (

prj_...

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-name-or-id>

This is the simplest path when you already have a project ID — no

.vercel/

directory needed.

使用

--project

参数直接定位到特定项目，无需执行
vercel link
命令。支持传入项目名称或项目ID（格式为

prj_...

）：

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-name-or-id>

当你已拥有项目ID时，这是最简单的操作方式——无需创建

.vercel/

目录。

Environment Variable Alternative

环境变量替代方案

Instead of flags, you can set these environment variables. The CLI recognizes them natively:

Variable	Purpose	Equivalent flag
`VERCEL_TOKEN`	Auth token	`--token`
`VERCEL_ORG_ID`	Team/org ID	`--scope`
`VERCEL_PROJECT_ID`	Project ID	`--project`

VERCEL_ORG_ID

and

VERCEL_PROJECT_ID

must be set together — setting only one causes an error. When both are set, the CLI skips

.vercel/project.json

entirely.

除了使用命令行参数，你也可以设置以下环境变量，CLI会自动识别它们：

变量名	用途	对应命令行参数
`VERCEL_TOKEN`	身份验证令牌	`--token`
`VERCEL_ORG_ID`	团队/组织ID	`--scope`
`VERCEL_PROJECT_ID`	项目ID	`--project`

VERCEL_ORG_ID

和

VERCEL_PROJECT_ID

必须同时设置——仅设置其中一个会导致错误。当两者都设置后，CLI会完全忽略

.vercel/project.json

文件。

Resolution Precedence

优先级顺序

Token:

--token

flag >

VERCEL_TOKEN

env var > stored auth in config.

Team/scope:

--scope

flag >

scope

vercel.json

currentTeam

in global config >

VERCEL_ORG_ID

Project:

--project

flag >

VERCEL_PROJECT_ID

env var >

.vercel/project.json

> interactive prompt.

令牌优先级：

--token

参数 >

VERCEL_TOKEN

环境变量 > 配置文件中存储的身份验证信息。

团队/范围优先级：

--scope

参数 >

vercel.json

中的

scope

配置 > 全局配置中的

currentTeam

VERCEL_ORG_ID

环境变量。

项目优先级：

--project

参数 >

VERCEL_PROJECT_ID

环境变量 >

.vercel/project.json

文件 > 交互式提示。

CLI Setup

CLI安装配置

bash

npm install -g vercel
vercel --version

Or use

npx

for one-off commands:

bash

npx vercel <command> --token "$VERCEL_TOKEN"

bash

npm install -g vercel
vercel --version

或者使用

npx

执行一次性命令：

bash

npx vercel <command> --token "$VERCEL_TOKEN"

Deploying a Project

项目部署

Always deploy as preview unless the user explicitly requests production.

除非用户明确要求生产环境部署，否则默认部署为预览环境。

Quick Deploy (have project ID — no linking needed)

快速部署（已有项目ID——无需关联）

When you already have a project ID (e.g.,

prj_...

), deploy directly:

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

Check status:

bash

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

Production deploy (only when explicitly requested):

bash

vercel deploy --prod --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

当你已拥有项目ID（例如

prj_...

）时，可直接部署：

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

查看部署状态：

bash

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

生产环境部署（仅在用户明确要求时执行）：

bash

vercel deploy --prod --token "$VERCEL_TOKEN" --scope <team> --project <project-id> -y --no-wait

Full Deploy Flow (no project ID)

完整部署流程（无项目ID）

Use this when you have a token and team but need to create or find a project.

当你拥有令牌和团队信息，但需要创建或查找项目时，使用此流程。

Step 1: Determine Project State

步骤1：确认项目状态

bash

undefined

bash

undefined

1. Does the project have a git remote?

1. 项目是否关联了Git远程仓库？

git remote get-url origin 2>/dev/null

2. Is it already linked to a Vercel project?

2. 项目是否已关联到Vercel项目？

cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

undefined

cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

undefined

Step 2: Link the Project

步骤2：关联项目

If no

.vercel/project.json

.vercel/repo.json

exists, link first.

With git remote (preferred):

bash

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

Reads the git remote and connects to the matching Vercel project. Creates

.vercel/repo.json

. More reliable than

vercel link

without

--repo

, which matches by directory name.

Without git remote:

bash

vercel link --token "$VERCEL_TOKEN" --scope <team> -y

Creates

.vercel/project.json

Link to a specific existing project by name:

bash

vercel link --project <project-name> --token "$VERCEL_TOKEN" --scope <team> -y

If the project is already linked, check

orgId

.vercel/project.json

.vercel/repo.json

to verify it matches the intended team. If not, re-link with the correct

--scope

如果不存在

.vercel/project.json

或

.vercel/repo.json

文件，需先执行关联操作。

通过Git远程仓库关联（推荐）：

bash

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

该命令会读取Git远程仓库信息，并关联到对应的Vercel项目，同时创建

.vercel/repo.json

文件。相比不带

--repo

参数的

vercel link

命令，此方式更可靠，后者仅通过目录名匹配项目。

无Git远程仓库时关联：

bash

vercel link --token "$VERCEL_TOKEN" --scope <team> -y

该命令会创建

.vercel/project.json

文件。

关联到指定现有项目（通过项目名称）：

bash

vercel link --project <project-name> --token "$VERCEL_TOKEN" --scope <team> -y

如果项目已关联，需检查

.vercel/project.json

或

.vercel/repo.json

中的

orgId

是否与目标团队一致。若不一致，需使用正确的

--scope

参数重新关联。

Step 3: Deploy

步骤3：部署项目

A) Git Push Deploy — has git remote (preferred)

The best long-term setup. Git pushes trigger automatic Vercel deployments.

Ask the user before pushing. Never push without explicit approval.

Commit and push:

bash

git add .
git commit -m "deploy: <description of changes>"
git push

Vercel builds automatically. Non-production branches get preview deployments; the production branch (usually
```
main
```
) gets a production deployment.

Retrieve the deployment URL:

bash

sleep 5
vercel ls --format json --token "$VERCEL_TOKEN" --scope <team>

The latest entry in the

deployments

array has the preview URL.

B) CLI Deploy — no git remote

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> -y --no-wait

--no-wait

returns immediately with the deployment URL. Check status:

bash

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

A) Git推送部署（已有Git远程仓库——推荐）

这是长期维护项目的最佳方式，Git推送会自动触发Vercel部署。

推送前需征得用户同意，切勿未经许可直接推送。

提交并推送代码：

bash

git add .
git commit -m "deploy: <变更描述>"
git push

Vercel会自动构建项目。非生产分支会生成预览部署链接；生产分支（通常为
```
main
```
）会生成生产部署链接。

获取部署链接：

bash

sleep 5
vercel ls --format json --token "$VERCEL_TOKEN" --scope <team>

deployments

数组中的最新条目即为预览部署链接。

B) CLI部署（无Git远程仓库）

bash

vercel deploy --token "$VERCEL_TOKEN" --scope <team> -y --no-wait

--no-wait

参数会立即返回部署链接，无需等待构建完成。查看部署状态：

bash

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

Deploying from a Remote Repository

从远程仓库部署

If the user wants to deploy code from a remote that isn't cloned locally:

Clone the repository:
bash
```
git clone <repo-url>
cd <repo-name>
```

Link to Vercel:

bash

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

Deploy via git push (if you have push access) or CLI deploy.

如果用户希望从本地未克隆的远程仓库部署代码：

克隆仓库：
bash
```
git clone <repo-url>
cd <repo-name>
```

关联到Vercel：

bash

vercel link --repo --token "$VERCEL_TOKEN" --scope <team> -y

通过Git推送（若有推送权限）或CLI命令完成部署。

About

.vercel/

Managing Environment Variables

环境变量管理

Run from a linked project directory, or use

--project

to target a specific project.

bash

undefined

可在已关联的项目目录中执行以下命令，或使用

--project

参数定位到特定项目。

bash

undefined

Set for all environments

为所有环境设置环境变量

echo "value" | vercel env add VAR_NAME --token "$VERCEL_TOKEN" --scope <team>

Set for a specific environment (production, preview, development)

为特定环境设置环境变量（production、preview、development）

echo "value" | vercel env add VAR_NAME production --token "$VERCEL_TOKEN" --scope <team>

List environment variables

列出所有环境变量

vercel env ls --token "$VERCEL_TOKEN" --scope <team>

Pull env vars to local .env file

将环境变量拉取到本地.env文件

vercel env pull --token "$VERCEL_TOKEN" --scope <team>

Remove a variable

删除环境变量

vercel env rm VAR_NAME --token "$VERCEL_TOKEN" --scope <team> -y

undefined

vercel env rm VAR_NAME --token "$VERCEL_TOKEN" --scope <team> -y

undefined

Inspecting Deployments

部署状态查看

bash

undefined

bash

undefined

List recent deployments

列出最近的部署记录

vercel ls --format json --token "$VERCEL_TOKEN" --scope <team>

Inspect a specific deployment

查看特定部署的详细信息

vercel inspect <deployment-url> --token "$VERCEL_TOKEN"

View build logs

查看构建日志

vercel logs <deployment-url> --token "$VERCEL_TOKEN"

undefined

vercel logs <deployment-url> --token "$VERCEL_TOKEN"

undefined

Managing Domains

域名管理

bash

undefined

bash

undefined

List domains

列出所有域名

vercel domains ls --token "$VERCEL_TOKEN" --scope <team>

Add a domain to the project

为项目添加域名

vercel domains add <domain> --token "$VERCEL_TOKEN" --scope <team>

undefined

vercel domains add <domain> --token "$VERCEL_TOKEN" --scope <team>

undefined

Working Agreement

操作规范

Always use
--token
on every Vercel CLI command. Never rely on local login state.
Use
--scope
and/or
--project
to target the correct team and project.
Do not run
vercel login
. Authentication is handled entirely by the access token.
Default to preview deployments. Only deploy to production when explicitly asked.
Ask before pushing to git. Never push commits without the user's approval.
Do not read or modify
.vercel/
files directly. The CLI manages this directory.
Do not curl/fetch deployed URLs to verify. Just return the link to the user.
Use
--format json
when structured output will help with follow-up steps (e.g.,
```
vercel ls
```
).
Use
-y
on commands that prompt for confirmation to avoid interactive blocking.

始终在Vercel CLI命令中使用
--token
参数，切勿依赖本地登录状态。
使用
--scope
和/或
--project
参数定位到正确的团队和项目。
切勿运行
vercel login
命令，所有身份验证操作均通过访问令牌完成。
默认部署到预览环境，仅在用户明确要求时部署到生产环境。
推送Git代码前需征得用户同意，切勿未经许可直接推送提交。
请勿直接读取或修改
.vercel/
目录下的文件，该目录由CLI自动管理。
请勿通过curl/fetch访问部署链接来验证，直接将链接返回给用户即可。
当结构化输出有助于后续操作时，使用
--format json
参数（例如
```
vercel ls
```
命令）。
在需要确认的命令中使用
-y
参数，避免交互式阻塞。

Troubleshooting

故障排查

Authentication Error

身份验证错误

If commands fail with

Authentication required

or similar:

The token may be expired or revoked. Ask the user for a fresh token or check the token source.
Verify the token is valid:
```
vercel whoami --token "$VERCEL_TOKEN"
```

如果命令执行失败并提示

Authentication required

或类似信息：

令牌可能已过期或被撤销，请向用户索要新的令牌或检查令牌来源。
验证令牌有效性：
```
vercel whoami --token "$VERCEL_TOKEN"
```

Wrong Team

团队错误

If deployments appear under the wrong team, verify

--scope

is correct:

bash

vercel whoami --token "$VERCEL_TOKEN" --scope <team>

如果部署记录显示在错误的团队下，请验证

--scope

参数是否正确：

bash

vercel whoami --token "$VERCEL_TOKEN" --scope <team>

Build Failure

构建失败

Check the build logs:

bash

vercel logs <deployment-url> --token "$VERCEL_TOKEN"

Common causes:

Missing dependencies — ensure
```
package.json
```
is complete and committed.
Missing environment variables — add them with
```
vercel env add
```
.
Framework misconfiguration — check
```
vercel.json
```
or framework-specific settings.
Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from
```
package.json
```
. Override with a
```
vercel.json
```
if detection is wrong.

查看构建日志：

bash

vercel logs <deployment-url> --token "$VERCEL_TOKEN"

常见原因：

依赖缺失——确保
```
package.json
```
文件完整且已提交。
环境变量缺失——使用
```
vercel env add
```
命令添加。
框架配置错误——检查
```
vercel.json
```
或框架特定配置。
Vercel会从
```
package.json
```
自动识别框架（Next.js、Remix、Vite等）。如果识别错误，可通过
```
vercel.json
```
文件手动指定。

CLI Not Installed

CLI未安装

bash

npm install -g vercel

bash

npm install -g vercel

vercel-cli-with-tokens

Original

Translation

Vercel CLI with Tokens

基于令牌的Vercel CLI使用方法

Authentication

身份验证

Scoping to a Team

指定团队

Targeting a Project

指定项目

Environment Variable Alternative

环境变量替代方案

Resolution Precedence

优先级顺序

CLI Setup

CLI安装配置

Deploying a Project

项目部署

Quick Deploy (have project ID — no linking needed)

快速部署（已有项目ID——无需关联）

Full Deploy Flow (no project ID)

完整部署流程（无项目ID）

Step 1: Determine Project State

步骤1：确认项目状态

1. Does the project have a git remote?

1. 项目是否关联了Git远程仓库？

2. Is it already linked to a Vercel project?

2. 项目是否已关联到Vercel项目？

Step 2: Link the Project

步骤2：关联项目

Step 3: Deploy

步骤3：部署项目

Deploying from a Remote Repository

从远程仓库部署

About .vercel/ Directory

关于.vercel/目录

Managing Environment Variables

环境变量管理

Set for all environments

为所有环境设置环境变量

Set for a specific environment (production, preview, development)

为特定环境设置环境变量（production、preview、development）

List environment variables

列出所有环境变量

Pull env vars to local .env file

将环境变量拉取到本地.env文件

Remove a variable

删除环境变量

Inspecting Deployments

部署状态查看

List recent deployments

列出最近的部署记录

Inspect a specific deployment

查看特定部署的详细信息

View build logs

查看构建日志

Managing Domains

域名管理

List domains

列出所有域名

Add a domain to the project

为项目添加域名

Working Agreement

操作规范

Troubleshooting

故障排查

Authentication Error

身份验证错误

Wrong Team

团队错误

Build Failure

构建失败

CLI Not Installed

CLI未安装

About
`.vercel/`
Directory

关于
`.vercel/`
目录