Vercel CLI 令牌认证部署

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 '^<VARIABLE_NAME>=' .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），提取团队 slug：

# 例如：从 "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="<org-id>"
export VERCEL_PROJECT_ID="<project-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 <team-slug> -y --no-wait

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

vercel deploy --prod --scope <team-slug> -y --no-wait

检查状态：

vercel inspect <deployment-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 <team-slug> -y

读取 git 远程仓库并连接到匹配的 Vercel 项目。会创建 .vercel/repo.json。比普通 vercel link（按目录名匹配）更可靠。

没有 git 远程仓库：

vercel link --scope <team-slug> -y

会创建 .vercel/project.json。

按名称链接到特定项目：

vercel link --project <project-name> --scope <team-slug> -y

如果项目已链接，检查 .vercel/project.json 或 .vercel/repo.json 中的 orgId，以确认匹配预期的团队。

链接后部署

A) Git Push 部署 —— 有 git 远程仓库（推荐）

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

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

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

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

   sleep 5
   vercel ls --format json --scope <team-slug>
   

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

B) CLI 部署 —— 没有 git 远程仓库

vercel deploy --scope <team-slug> -y --no-wait

检查状态：

vercel inspect <deployment-url>

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

1. 克隆仓库：

   git clone <repo-url>
   cd <repo-name>
   

2. 链接到 Vercel：

   vercel link --repo --scope <team-slug> -y
   

3. 通过 git push（如果你有推送权限）或 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 project inspect 或 vercel link 来检测状态——它们会交互式地提示或默默地作为副作用进行链接。vercel ls 是安全的（在未链接的目录中，它会默认显示该范围的所有部署）。vercel whoami 在任何位置都是安全的。

管理环境变量

# 为所有环境设置
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# 为特定环境设置（production、preview、development）
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# 列出环境变量
vercel env ls --scope <team-slug>

# 将环境变量拉取到本地 .env.local 文件
vercel env pull --scope <team-slug>

# 删除变量
vercel env rm VAR_NAME --scope <team-slug> -y

检查部署

# 列出最近的部署
vercel ls --format json --scope <team-slug>

# 检查特定部署
vercel inspect <deployment-url>

# 查看构建日志（需要 Vercel CLI v35+）
vercel inspect <deployment-url> --logs

# 查看运行时请求日志（默认实时跟踪；添加 --no-follow 获取一次性快照）
vercel logs <deployment-url>

管理域名

# 列出域名
vercel domains ls --scope <team-slug>

# 为项目添加域名 —— 已链接或通过环境变量链接的目录（1 个参数）
vercel domains add <domain> --scope <team-slug>

# 添加域名 —— 未链接的目录（需要 <project> 位置参数）
vercel domains add <domain> <project> --scope <team-slug>

Stripe 项目计划变更

如果此项目由 Stripe Projects 管理。在运行任何收费或破坏性的计划变更之前，务必询问用户——升级会从真实信用卡扣费，降级会移除席位。

首先运行 stripe projects status --json 确认 Vercel 资源的本地名称。以下示例假定默认名称（vercel-plan）；如果在 stripe projects add 时重命名了，请替换为实际名称。

• 升级到 Pro： stripe projects add vercel/pro（或 stripe projects upgrade vercel-plan pro）
• 降级到 Hobby： stripe projects downgrade vercel-plan hobby

Pro 提供的内容

• 每月 $20 平台费用，包含每月 $20 使用额度。
• 新项目默认使用 Turbo 构建机器（30 vCPU，60 GB 内存）——比 Hobby 方案构建速度显著更快。
• 1 个部署席位 + 无限免费 Viewer 席位（只读协作者、预览评论）。
• 更高的包含配额（每月 1 TB 快速数据传输、1000 万 Edge 请求）。
• 付费附加功能：SAML SSO、HIPAA BAA、Flags Explorer、Observability Plus、Speed Insights、Web Analytics Plus。

完整详情：https://vercel.com/docs/plans/pro-plan

工作约定

• 永远不要将 VERCEL_TOKEN 作为 --token 参数传递。 将其导出为环境变量，让 CLI 原生读取。
• 在询问用户之前先检查环境中的令牌。 首先检查当前环境变量和 .env 文件。
• 默认进行预览部署。 仅在明确要求时部署到生产环境。
• 推送 git 之前询问用户。 未经用户批准，绝不推送提交。
• 不要直接修改 .vercel/ 文件。 CLI 管理该目录。读取它们（例如验证 orgId）是可以的。
• 不要 curl/fetch 已部署的 URL 来验证。 只需将链接返回给用户。
• 在需要结构化输出以帮助后续步骤时，使用 --format json。
• 在需要确认的命令上使用 -y，以避免交互式阻塞。

故障排除

未找到令牌

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

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

认证错误

如果 CLI 失败并显示 Authentication required：

• 令牌可能已过期或无效。
• 验证：vercel whoami（使用环境变量中的 VERCEL_TOKEN）。
• 向用户请求一个新令牌。

错误的团队

验证范围是否正确：

vercel whoami --scope <team-slug>

构建失败

检查构建日志：

vercel inspect <deployment-url> --logs

常见原因：

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

CLI 未安装

npm install -g vercel