本技能用于首次配置 Vercel:安装 CLI、认证、关联项目并拉取环境变量。前提是已安装 Node.js 18+,并拥有 npm、pnpm 或 yarn 以及 Vercel 账号。
安装:全局安装推荐 npm install -g vercel@latest,也可项目本地安装 npm install --save-dev vercel@latest,随后用 vercel --version 验证。
认证有两种途径。交互式登录执行 vercel login,会打开浏览器进行 OAuth,并将令牌保存到 ~/.config/com.vercel.cli;也可 vercel login your@email.com,或使用 --github、--gitlab。CI/CD 场景则用无头令牌:在 Vercel 控制台 Settings > Tokens 或通过 API 创建令牌,然后 export VERCEL_TOKEN="your-access-token-here",CLI 会自动读取;可用 vercel whoami 验证。需要指定团队或项目时设置 VERCEL_ORG_ID 与 VERCEL_PROJECT_ID。
关联本地项目使用 vercel link,或 vercel link --project my-project-name,链接信息写入 .vercel/project.json。可用 REST API 验证令牌,例如 curl -s -H "Authorization: Bearer $VERCEL_TOKEN" https://api.vercel.com/v9/projects;列出团队用 https://api.vercel.com/v2/teams。拉取环境变量执行 vercel env pull .env.development.local,或加 --environment=preview。
令牌作用域分为全账号、团队级、项目级;令牌可设有效期,CI 建议用短效期(如 90 天)并定期轮换。
常见错误:未登录或无 VERCEL_TOKEN 会提示 No token found;令牌失效会提示 Invalid token,需重新生成;全局安装报 EACCES 可用 npx vercel 或 --prefix ~/.npm-global;团队找不到需核对 VERCEL_ORG_ID;fetch failed 多为网络或代理问题。建议将 .vercel/ 与 .env*.local 加入 .gitignore。资料未提供后续部署以外的更多细节。