vercel-cli-with-tokens

使用 Token 的 Vercel CLI

使用基于 Token 的身份验证，通过 CLI 在 Vercel 上部署和管理项目，无需依赖 vercel login。

步骤 1：查找 Vercel Token

运行任何 Vercel CLI 命令之前，请先确定 Token 的来源。按以下顺序检查这些情况：

A) 环境中已设置 VERCEL_TOKEN

printenv VERCEL_TOKEN

如果返回了值，就可以继续了。跳至步骤 2。

B) .env 文件中有名为 VERCEL_TOKEN 的 Token

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

如果找到，请将其导出：

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

C) .env 文件中有以其他名称保存的 Token

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

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

检查输出，确定哪个变量保存了 Token，然后将其导出为 VERCEL_TOKEN：

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

D) 未找到 Token——询问用户

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

---

**重要：**将 VERCEL_TOKEN 导出为环境变量后，Vercel CLI 会自动读取它——不要通过 --token 标志传入 Token。将密钥放在命令行参数中会导致其出现在 Shell 历史记录和进程列表中。

# Bad — token visible in shell history and process listings
vercel deploy --token "vca_abc123"

# Good — CLI reads VERCEL_TOKEN from the environment
export VERCEL_TOKEN="vca_abc123"
vercel deploy

步骤 2：查找项目和团队

同样，检查项目 ID 和团队范围。这些信息可让 CLI 定位正确的项目，无需运行 vercel link。

# Check environment
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

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

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

# e.g. "my-team" from "https://vercel.com/my-team/my-project"
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——需要链接）

适用于有 Token 和团队信息，但没有现成项目 ID 的情况。

先检查项目状态

# Does the project have a git remote?
git remote get-url origin 2>/dev/null

# Is it already linked to a Vercel project?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

链接项目

有 git remote（首选）：

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

读取 git remote，并连接到匹配的 Vercel 项目。创建 .vercel/repo.json。与普通的 vercel link 相比，这种方式更可靠；普通的 vercel link 会按目录名称匹配。

没有 git remote：

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 remote（首选）

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

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

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

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

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

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

B) CLI 部署——没有 git remote

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 在任何位置都可以安全运行。

管理环境变量

# Set for all environments
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# Set for a specific environment (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# List environment variables
vercel env ls --scope <team-slug>

# Pull env vars to local .env.local file
vercel env pull --scope <team-slug>

# Remove a variable
vercel env rm VAR_NAME --scope <team-slug> -y

检查部署

# List recent deployments
vercel ls --format json --scope <team-slug>

# Inspect a specific deployment
vercel inspect <deployment-url>

# View build logs (requires Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
vercel logs <deployment-url>

管理域名

# List domains
vercel domains ls --scope <team-slug>

# Add a domain to the project — linked or env-linked directory (1 arg)
vercel domains add <domain> --scope <team-slug>

# Add a domain — unlinked directory (requires <project> positional)
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 个部署席位 + 无限量免费 Viewer 席位（只读协作者，可发表评论预览）。
• 更高的包含配额（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