用访问令牌在 Vercel 上非交互式部署与管理项目

当需要用 Vercel CLI 以 token 认证（而非 vercel login 交互登录）来部署、配置环境变量、管理域名时使用。

适用场景

解决思路

1. 先定位 Vercel token：按顺序检查 (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 token（通常以 `vca_` 开头），用 `grep -i 'vercel' .env 2>/dev/null` 查找并导出为 VERCEL_TOKEN；(D) 都没有则让用户去 vercel.com/account/tokens 创建并提供。
2. 导出 VERCEL_TOKEN 为环境变量后，Vercel CLI 会原生读取它，**不要**用 `--token` 参数传递（会暴露在 shell 历史和进程列表中）。
3. 定位项目与团队：用 `printenv VERCEL_PROJECT_ID` 和 `printenv VERCEL_ORG_ID` 检查环境，或 `grep -i 'vercel' .env 2>/dev/null` 检查 .env。
4. 若有项目 URL（如 https://vercel.com/my-team/my-project），用 `echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1` 提取团队 slug。
5. 若同时有 VERCEL_ORG_ID 和 VERCEL_PROJECT_ID，导出它们，CLI 会自动使用并跳过 `.vercel/` 目录；注意两者必须同时设置，只设一个会报错。
6. 确保 Vercel CLI 已安装并更新：`npm install -g vercel` 然后 `vercel --version`。
7. 部署时默认使用 preview，除非用户明确要求 production。
8. 快速部署（已有 project ID，无需 link）：当 VERCEL_TOKEN 和 VERCEL_PROJECT_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>` 检查状态。
9. 完整部署流程（无 project ID，需要 link）：先检查项目状态，用 `git remote get-url origin 2>/dev/null` 看是否有 git remote，用 `cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null` 看是否已链接。
10. 链接项目：有 git remote 时（首选）用 `vercel link --repo --scope <team-slug> -y`（会创建 `.vercel/repo.json`，比普通 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 是否匹配目标团队。
11. 链接后部署方式 A（Git Push 部署，有 git remote 时首选）：先询问用户再推送，绝不未经批准推送；然后 `git add .`、`git commit -m "deploy: <description of changes>"`、`git push`；Vercel 自动构建，非生产分支得到 preview 部署；用 `sleep 5` 后 `vercel ls --format json --scope <team-slug>` 获取部署 URL，在 deployments 数组中找最新条目。
12. 链接后部署方式 B（CLI 部署，无 git remote）：`vercel deploy --scope <team-slug> -y --no-wait`，再用 `vercel inspect <deployment-url>` 检查状态。
13. 从远程仓库部署（代码未在本地克隆）：`git clone <repo-url>` 并 `cd <repo-name>`，然后 `vercel link --repo --scope <team-slug> -y`，再通过 git push（若有推送权限）或 CLI 部署。
14. 了解 `.vercel/` 目录：链接的项目有 `.vercel/project.json`（来自 `vercel link`，含 projectId 和 orgId）或 `.vercel/repo.json`（来自 `vercel link --repo`，含 orgId、remoteName 和 projects 映射）；当 VERCEL_ORG_ID + VERCEL_PROJECT_ID 都已设置时不需要它。
15. 不要在未链接的目录运行 `vercel project inspect` 或 `vercel link` 来检测状态（会交互式提示或静默链接产生副作用）；`vercel ls` 是安全的（未链接目录默认显示该 scope 的所有部署），`vercel whoami` 在任何地方都安全。
16. 管理环境变量：`echo "value" | vercel env add VAR_NAME --scope <team-slug>` 设置所有环境；加环境名（production/preview/development）设置特定环境；`vercel env ls --scope <team-slug>` 列出；`vercel env pull --scope <team-slug>` 拉取到本地 .env.local；`vercel env rm VAR_NAME --scope <team-slug> -y` 删除。
17. 检查部署：`vercel ls --format json --scope <team-slug>` 列出最近部署；`vercel inspect <deployment-url>` 检查特定部署；`vercel inspect <deployment-url> --logs` 查看构建日志（需 CLI v35+）；`vercel logs <deployment-url>` 查看运行时请求日志（默认实时跟随，加 --no-follow 为一次性快照）。
18. 管理域名：`vercel domains ls --scope <team-slug>` 列出；已链接或环境链接目录用 `vercel domains add <domain> --scope <team-slug>`（1 个参数）；未链接目录用 `vercel domains add <domain> <project> --scope <team-slug>`（需要 project 位置参数）。
19. Stripe Projects 计划变更：若项目由 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`。
20. 工作约定：绝不把 VERCEL_TOKEN 作为 --token 参数传递；询问用户前先检查环境和 .env 中的 token；默认 preview 部署，仅在明确要求时生产部署；推送 git 前先询问；不要直接修改 `.vercel/` 文件（CLI 管理该目录，读取可以）；不要 curl/fetch 已部署 URL 来验证，直接把链接返回给用户；需要结构化输出时用 `--format json`；对会提示确认的命令用 `-y` 避免交互阻塞。
21. 故障排查：token 未找到时用 `printenv | grep -i vercel` 和 `grep -i vercel .env 2>/dev/null` 检查；认证错误时 token 可能过期或无效，用 `vercel whoami` 验证并让用户提供新 token；团队错误时用 `vercel whoami --scope <team-slug>` 验证 scope；构建失败时用 `vercel inspect <deployment-url> --logs` 查看日志，常见原因包括缺少依赖（确保 package.json 完整并已提交）、缺少环境变量（用 `vercel env add` 添加）、框架配置错误（检查 vercel.json，Vercel 会从 package.json 自动检测框架，检测错误时用 vercel.json 覆盖）；CLI 未安装时用 `npm install -g vercel`。

适用边界 · 注意事项

• 需要交互式登录或无法获取访问令牌的场景（本技能依赖 token 认证）。
• 用户未明确要求生产部署时，不应部署到 production。
• 未经用户明确批准，不应推送 git 提交。