SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场vercel-cli-with-tokens

vercel-cli-with-tokens

部署与运维

查看项目

更新于 10-14 05:35

技能介绍

用途

本技能用于在 Vercel 上部署和管理项目，采用基于令牌（Token）的认证方式，避免使用交互式的 vercel login 登录流程。适用于需要以自动化或非交互方式操作 Vercel CLI 的场景。

主要能力

  • 在环境变量或 .env 文件中定位 Vercel Token（通常以 vca_ 开头）、项目 ID 和团队范围。
  • 安装和更新 Vercel CLI。
  • 部署项目：在已设置 VERCEL_TOKEN 和 VERCEL_PROJECT_ID 时可快速部署；无项目 ID 时先链接项目再部署。
  • 通过 git push 触发自动部署，或使用 CLI 直接部署。
  • 管理环境变量：添加、列出、拉取、删除。
  • 检查部署状态、查看构建日志和运行时请求日志。
  • 管理域名：列出和添加域名。
  • 在 Stripe Projects 管理场景下变更 Vercel 套餐计划。

使用方式

定位 Token

依次检查以下情形：

  1. 环境变量中已设置 VERCEL_TOKEN：
printenv VERCEL_TOKEN
  1. .env 文件中存在 VERCEL_TOKEN：
grep '^VERCEL_TOKEN=' .env 2>/dev/null
export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
  1. .env 文件中以其他名称存在：
grep -i 'vercel' .env 2>/dev/null
export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
  1. 未找到 Token 时，向用户索取。用户可在 vercel.com/account/tokens 创建访问令牌。

重要：将 VERCEL_TOKEN 导出为环境变量后，Vercel CLI 会原生读取它，不要通过 --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

定位项目与团队

检查项目 ID 和团队范围：

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

从项目 URL 提取团队 slug：

echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

如果同时设置了 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID，CLI 会自动使用它们并跳过 .vercel/ 目录。注意：两个变量必须一起设置，只设置其中一个会报错。

CLI 安装

npm install -g vercel
vercel --version

部署项目

除非用户明确要求生产环境，否则始终以预览方式部署。

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

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

完整部署流程（无项目 ID，需先链接）：

git remote get-url origin 2>/dev/null
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
vercel link --repo --scope <team-slug> -y
vercel link --scope <team-slug> -y
vercel link --project <project-name> --scope <team-slug> -y

链接后通过 git push 部署（需先获得用户同意）：

git add .
git commit -m "deploy: <description of changes>"
git push
sleep 5
vercel ls --format json --scope <team-slug>

无 git remote 时通过 CLI 部署：

vercel deploy --scope <team-slug> -y --no-wait
vercel inspect <deployment-url>

从远程仓库部署：

git clone <repo-url>
cd <repo-name>
vercel link --repo --scope <team-slug> -y

.vercel/ 目录说明

已链接项目包含 .vercel/project.json 或 .vercel/repo.json。当环境变量中同时设置了 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>
echo "value" | vercel env add VAR_NAME production --scope <team-slug>
vercel env ls --scope <team-slug>
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 inspect <deployment-url> --logs
vercel logs <deployment-url>

管理域名

vercel domains ls --scope <team-slug>
vercel domains add <domain> --scope <team-slug>
vercel domains add <domain> <project> --scope <team-slug>

Stripe Projects 套餐变更

在执行任何付费或破坏性计划变更前需询问用户。先运行 stripe projects status --json 确认 Vercel 资源的本地名称。

  • 升级到 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 内存）；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 参数传递，而是导出为环境变量。
  • 先检查环境和 .env 文件中的令牌，再询问用户。
  • 默认使用预览部署，仅在明确要求时部署到生产环境。
  • 推送 Git 前需征得用户同意。
  • 不要直接修改 .vercel/ 文件，由 CLI 管理。
  • 不要 curl/fetch 已部署的 URL 进行验证，直接将链接返回给用户。
  • 需要结构化输出时使用 --format json。
  • 对需要确认的命令使用 -y 以避免交互阻塞。

故障排查

  • 未找到 Token：printenv | grep -i vercel; grep -i vercel .env 2>/dev/null
  • 认证错误：Token 可能过期或无效，使用 vercel whoami 验证，向用户索取新令牌。
  • 团队错误：使用 vercel whoami --scope <team-slug> 验证范围。
  • 构建失败：使用 vercel inspect <deployment-url> --logs 查看构建日志。常见原因包括缺少依赖、缺少环境变量、框架配置错误（Vercel 从 package.json 自动检测框架，可通过 vercel.json 覆盖）。
  • CLI 未安装：npm install -g vercel

适用场景与限制

适用场景：需要以令牌认证方式在 Vercel 上以非交互方式部署和管理项目、管理环境变量与域名、查看部署与日志、以及在 Stripe Projects 场景下管理 Vercel 套餐。

限制：资料中未提供除已列出外的其他平台支持、定价细节或效果保证；如需创建访问令牌，需在 vercel.com/account/tokens 进行；具体项目与团队信息需由环境变量或 .env 文件提供，缺失时需向用户索取。