vercel-cli-with-tokens

使用令牌的 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 Projects 计划变更

如果此项目由 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 个部署席位 + 无限免费查看者席位（只读协作者、预览评论）。
• 更高的包含配额（每月 1 TB 快速数据传输，1000 万边缘请求）。
• 可用的付费附加组件：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