Vercel CLI 配合令牌使用

使用基于令牌认证的 CLI 在 Vercel 上部署和管理项目，无需依赖 vercel login。

步骤 1：定位 Vercel 令牌

在运行任何 Vercel CLI 命令之前，确定令牌的来源。按顺序处理以下场景：

A) VERCEL_TOKEN 已设置在环境中

printenv VERCEL_TOKEN

如果有返回值，则已就绪。跳到步骤 2。

B) 令牌在 .env 文件中，变量名为 VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

如果找到，将其导出：

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) 令牌在 .env 文件中，但变量名不同

查找任何看起来像 Vercel 令牌的变量（Vercel 令牌通常以 vca_ 开头）：

grep -i 'vercel' .env 2>/dev/null

检查输出以确定哪个变量持有令牌，然后将其导出为 VERCEL_TOKEN：

export VERCEL_TOKEN=$(grep '^<变量名>=' .env | cut -d= -f2-)

D) 未找到令牌 — 询问用户

如果上述方法都未找到令牌，请用户提供一个。他们可以在 vercel.com/account/tokens 创建 Vercel 访问令牌。

重要提示： 一旦 VERCEL_TOKEN 作为环境变量导出，Vercel CLI 会自动读取它 — 不要将其作为 --token 标志传递。将密钥放在命令行参数中会使其暴露在 shell 历史和进程列表中。

# 不好 — 令牌在 shell 历史和进程列表中可见
vercel deploy --token "vca_abc123"

# 好 — CLI 从环境变量读取 VERCEL_TOKEN
export VERCEL_TOKEN="vca_abc123"
vercel deploy

步骤 2：定位项目和团队

同样，检查项目 ID 和团队范围。这允许 CLI 定位到正确的项目，无需 vercel link。

# 检查环境
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# 或检查 .env
grep -i 'vercel' .env 2>/dev/null

如果有项目 URL（例如 https://vercel.com/my-team/my-project），提取团队标识：

# 例如从 "https://vercel.com/my-team/my-project" 提取 "my-team"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

如果环境中同时有 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID，导出它们 — CLI 将自动使用这些，并跳过任何 .vercel/ 目录：

export VERCEL_ORG_ID="<组织ID>"
export VERCEL_PROJECT_ID="<项目ID>"

注意：VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 必须一起设置 — 只设置一个会导致错误。

CLI 设置

确保 Vercel CLI 已安装：

npm install -g vercel
vercel --version

部署项目

除非用户明确要求生产环境，否则始终部署为预览版。根据已有信息选择一种方法。

快速部署（已有项目 ID — 无需链接）

当环境中设置了 VERCEL_TOKEN 和 VERCEL_PROJECT_ID 时，直接部署：

vercel deploy -y --no-wait

使用团队范围（通过 VERCEL_ORG_ID 或 --scope）：

vercel deploy --scope <团队标识> -y --no-wait

生产环境（仅在明确要求时）：

vercel deploy --prod --scope <团队标识> -y --no-wait

检查状态：

vercel inspect <部署URL>

完整部署流程（无项目 ID — 需要链接）

当你有令牌和团队但没有现有项目 ID 时使用此方法。

先检查项目状态

# 项目是否有 git 远程仓库？
git remote get-url origin 2>/dev/null

# 是否已链接到 Vercel 项目？
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

链接项目

有 git 远程仓库（优先）：

vercel link --repo --scope <团队标识> -y

读取 git 远程仓库并连接到匹配的 Vercel 项目。创建 .vercel/repo.json。比普通 vercel link 更可靠，后者通过目录名称匹配。

无 git 远程仓库：

vercel link --scope <团队标识> -y

创建 .vercel/project.json。

按名称链接到特定项目：

vercel link --project <项目名> --scope <团队标识> -y

如果项目已链接，检查 .vercel/project.json 或 .vercel/repo.json 中的 orgId 以验证它是否与预期团队匹配。

链接后部署

A) Git 推送部署 — 有 git 远程仓库（优先）

Git 推送会触发自动 Vercel 部署。

1. 在推送前询问用户。 未经明确批准绝不推送。
2. 提交并推送：

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

3. Vercel 自动构建。非生产分支获得预览部署。
4. 获取部署 URL：

   sleep 5
   vercel ls --format json --scope <团队标识>
   

   在 deployments 数组中找到最新条目。

B) CLI 部署 — 无 git 远程仓库

vercel deploy --scope <团队标识> -y --no-wait

检查状态：

vercel inspect <部署URL>

从远程仓库部署（代码未在本地克隆）

1. 克隆仓库：

   git clone <仓库URL>
   cd <仓库名>
   

2. 链接到 Vercel：

   vercel link --repo --scope <团队标识> -y
   

3. 通过 git 推送（如果有推送权限）或 CLI 部署进行部署。

关于 .vercel/ 目录

链接的项目有两者之一：

• .vercel/project.json — 来自 vercel link。包含 projectId 和 orgId。
• .vercel/repo.json — 来自 vercel link --repo。包含 orgId、remoteName 和 projects 映射。

当环境中同时设置了 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 时，不需要这些。

不要在未链接的目录中运行 vercel ls、vercel project inspect 或 vercel link 来检测状态——它们会交互式地提示或因副作用而静默链接。只有 vercel whoami 可以在任何地方安全运行。

管理环境变量

# 为所有环境设置
echo "值" | vercel env add VAR_NAME --scope <团队标识>

# 为特定环境设置（production、preview、development）
echo "值" | vercel env add VAR_NAME production --scope <团队标识>

# 列出环境变量
vercel env ls --scope <团队标识>

# 拉取环境变量到本地 .env 文件
vercel env pull --scope <团队标识>

# 移除变量
vercel env rm VAR_NAME --scope <团队标识> -y

检查部署

# 列出最近的部署
vercel ls --format json --scope <团队标识>

# 检查特定部署
vercel inspect <部署URL>

# 查看构建日志
vercel logs <部署URL>

管理域名

# 列出域名
vercel domains ls --scope <团队标识>

# 向项目添加域名
vercel domains add <域名> --scope <团队标识>

工作约定

• 绝不要将 VERCEL_TOKEN 作为 --token 标志传递。 将其导出为环境变量，让 CLI 本地读取。
• 在询问用户之前先检查环境中的令牌。 首先检查当前环境和 .env 文件。
• 默认使用预览部署。 仅在明确要求时才部署到生产环境。
• 在推送到 git 前询问用户。 未经用户批准绝不推送提交。
• 不要直接读取或修改 .vercel/ 文件。 CLI 管理此目录。
• 不要 curl/fetch 已部署的 URL 来验证。 只需将链接返回给用户。
• 使用 --format json 当结构化输出有助于后续步骤时。
• 使用 -y 用于会提示确认的命令，以避免交互式阻塞。

故障排除

未找到令牌

检查环境和任何存在的 .env 文件：

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

认证错误

如果 CLI 失败并显示 需要认证：

• 令牌可能已过期或无效。
• 验证：vercel whoami（使用环境中的 VERCEL_TOKEN）。
• 请用户提供新的令牌。

团队错误

验证范围是否正确：

vercel whoami --scope <团队标识>

构建失败

检查构建日志：

vercel logs <部署URL>

常见原因：

• 缺少依赖项 — 确保 package.json 完整并已提交。
• 缺少环境变量 — 使用 vercel env add 添加。
• 框架配置错误 — 检查 vercel.json。Vercel 会从 package.json 自动检测框架（Next.js、Remix、Vite 等）；如果检测错误，可通过 vercel.json 覆盖。

CLI 未安装

npm install -g vercel