使用令牌的 Vercel CLI
使用基于令牌的身份验证，通过CLI在Vercel上部署和管理项目，无需依赖vercel login。
第一步：找到 Vercel 令牌
在运行任何 Vercel CLI 命令之前，先确定令牌的来源。按以下顺序逐一检查：
A）VERCEL_TOKEN 已在环境中设置
printenv VERCEL_TOKEN
如果返回了值，就准备好了。直接跳到第二步。
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
第二步：定位项目和团队
类似地，检查项目 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 <团队-slug> -y --no-wait
生产环境（仅在明确要求时）：
vercel deploy --prod --scope <团队-slug> -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 <团队-slug> -y
读取 git 远程仓库并连接到匹配的 Vercel 项目。创建 .vercel/repo.json。比普通的 vercel link 更可靠，后者根据目录名称匹配。
没有 git 远程仓库：
vercel link --scope <团队-slug> -y
创建 .vercel/project.json。
按项目名称链接到特定项目：
vercel link --project <项目名称> --scope <团队-slug> -y
如果项目已链接，请检查 .vercel/project.json 或 .vercel/repo.json 中的 orgId，以确认它匹配预期的团队。
链接后部署
A）Git 推送部署——有 git 远程仓库（推荐）
Git 推送会触发自动 Vercel 部署。
- 在推送前询问用户。 未经明确批准，绝不推送。
- 提交并推送：
git add . git commit -m "deploy: <更改描述>" git push - Vercel 自动构建。非生产分支会获得预览部署。
- 获取部署 URL：
sleep 5 vercel ls --format json --scope <团队-slug>deployments数组中找到最新条目。
B）CLI 部署——没有 git 远程仓库
vercel deploy --scope <团队-slug> -y --no-wait
检查状态：
vercel inspect <部署-url>
从远程仓库部署（代码未在本地克隆）
- 克隆仓库：
git clone <仓库-url> cd <仓库名称> - 链接到 Vercel：
vercel link --repo --scope <团队-slug> -y - 通过 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 project inspect 或 vercel link 来检测状态——它们会以交互方式提示或静默链接，产生副作用。vercel ls 是安全的（在未链接的目录中，它默认显示该范围的所有部署）。vercel whoami 在任何地方都是安全的。
管理环境变量
# 为所有环境设置
echo "value" | vercel env add VAR_NAME --scope <团队-slug>
# 为特定环境设置（production, preview, development）
echo "value" | vercel env add VAR_NAME production --scope <团队-slug>
# 列出环境变量
vercel env ls --scope <团队-slug>
# 将环境变量拉取到本地 .env.local 文件
vercel env pull --scope <团队-slug>
# 删除变量
vercel env rm VAR_NAME --scope <团队-slug> -y
检查部署
# 列出最近部署
vercel ls --format json --scope <团队-slug>
# 检查特定部署
vercel inspect <部署-url>
# 查看构建日志（需要 Vercel CLI v35+）
vercel inspect <部署-url> --logs
# 查看运行时请求日志（默认实时跟踪；添加 --no-follow 获取一次性快照）
vercel logs <部署-url>
管理域名
# 列出域名
vercel domains ls --scope <团队-slug>
# 向项目添加域名——已链接或通过环境变量链接的目录（1 个参数）
vercel domains add <域名> --scope <团队-slug>
# 添加域名——未链接的目录（需要 <项目> 位置参数）
vercel domains add <域名> <项目> --scope <团队-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文件。 - 默认使用预览部署。 仅在明确要求时才部署到生产环境。
- 推送前先询问用户。 未经用户批准，绝不推送提交。
- 不要直接修改
.vercel/文件。 CLI 管理此目录。读取它们（例如验证orgId）是可以的。 - 不要 curl/获取已部署的 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 <团队-slug>
构建失败
检查构建日志：
vercel inspect <部署-url> --logs
常见原因：
- 缺失依赖——确保
package.json完整且已提交。 - 缺失环境变量——使用
vercel env add添加。 - 框架配置错误——检查
vercel.json。Vercel 从package.json自动检测框架（Next.js、Remix、Vite 等）；如果检测错误，可通过vercel.json覆盖。
CLI 未安装
npm install -g vercel