Skip to main content

Vercel CLI 自动化部署完整教程

📦 安装 Vercel CLI​

全局安装​

npm i -g vercel

验证安装​

vercel --version
# 输出: Vercel CLI 48.10.2 (或更高版本)

🔐 登录和认证​

登录 Vercel​

vercel login

选择登录方式：

  • GitHub
  • GitLab
  • Bitbucket
  • Email

查看当前登录用户​

vercel whoami

登出​

vercel logout

🚀 基础部署命令​

1. 首次部署（开发环境）​

vercel

# 或使用别名
vercel deploy

交互式问题：

? Set up and deploy "~/path/to/project"? [Y/n] Y
? Which scope should contain your project? <选择账户>
? Link to existing project? [y/N] N
? What's your project's name? blog-site
? In which directory is your code located? ./

2. 部署到生产环境​

vercel --prod

# 或使用长格式
vercel --production

3. 静默部署（跳过确认）​

vercel --yes

# 生产环境静默部署
vercel --prod --yes

🔧 部署配置选项​

环境变量​

# 设置环境变量
vercel --env NODE_ENV=production

# 设置多个环境变量
vercel --env API_KEY=xxx --env DB_URL=yyy

# 从文件加载环境变量
vercel --env-file=.env.production

指定项目名称​

vercel --name my-project

指定输出目录​

vercel --output build

指定构建命令​

vercel --build-env CUSTOM_VAR=value

强制重新构建​

vercel --force

📋 项目管理命令​

列出所有部署​

vercel ls

# 列出指定项目的部署
vercel ls blog-site

# 限制结果数量
vercel ls --count 10

查看项目信息​

vercel inspect

# 查看指定 URL 的部署信息
vercel inspect <deployment-url>

删除部署​

# 删除指定部署
vercel rm <deployment-url>

# 删除项目
vercel rm blog-site --yes

🔗 项目链接管理​

链接到现有项目​

vercel link

# 或在部署时链接
vercel --link

取消项目链接​

vercel unlink

查看链接状态​

vercel project ls

📊 日志和调试​

查看部署日志​

vercel logs

# 查看指定部署的日志
vercel logs <deployment-url>

# 实时查看日志
vercel logs --follow
vercel logs -f

# 查看构建日志
vercel logs --build

查看函数日志​

vercel logs --function=api/hello

🌍 域名管理​

添加域名​

vercel domains add example.com

列出域名​

vercel domains ls

删除域名​

vercel domains rm example.com

为部署设置别名​

vercel alias <deployment-url> <custom-domain>

# 示例
vercel alias blog-site-xxx.vercel.app blog.example.com

🔒 密钥和环境变量管理​

添加环境变量​

vercel env add

# 交互式添加：
# ? What's the name of the variable? API_KEY
# ? What's the value? your-secret-key
# ? Add to which Environments? Production, Preview, Development

列出环境变量​

vercel env ls

拉取环境变量到本地​

vercel env pull .env.local

删除环境变量​

vercel env rm API_KEY

📦 高级部署命令​

部署特定分支​

vercel --prod --branch main

部署到特定区域​

vercel --regions sfo1

# 多个区域
vercel --regions sfo1,cdg1

设置部署超时​

vercel --timeout 60s

跳过自动检测框架​

vercel --no-framework

🔄 CI/CD 集成命令​

GitHub Actions 中使用​

# 安装
- run: npm i -g vercel

# 拉取项目配置
- run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

# 构建
- run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

# 部署
- run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

使用 Token 认证​

vercel --token <your-token>

# 示例
vercel --prod --token xxx --yes

📝 项目配置命令​

列出所有项目​

vercel project ls

添加项目​

vercel project add

删除项目​

vercel project rm blog-site

🎯 实用组合命令​

完整部署流程​

# 1. 登录
vercel login

# 2. 链接项目（首次）
vercel link

# 3. 拉取环境变量
vercel env pull

# 4. 本地构建测试
npm run build

# 5. 部署到预览环境
vercel

# 6. 确认无误后部署到生产
vercel --prod

快速重新部署​

# 获取最新部署
vercel ls --count 1

# 部署到生产
vercel --prod --yes

回滚到指定版本​

# 1. 列出所有部署
vercel ls

# 2. 将旧版本设为生产环境
vercel alias <old-deployment-url> production

🔍 常用命令速查​

命令说明
vercel部署到预览环境
vercel --prod部署到生产环境
vercel ls列出所有部署
vercel logs查看日志
vercel inspect查看部署详情
vercel env ls列出环境变量
vercel env pull拉取环境变量
vercel domains ls列出域名
vercel alias设置域名别名
vercel rm删除部署
vercel link链接项目
vercel whoami查看当前用户

📱 Vercel CLI 配置文件​

vercel.json 配置示例​

{
  "version": 2,
  "name": "blog-site",
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "installCommand": "npm install",
  "devCommand": "npm start",
  "framework": null,
  "regions": ["sfo1"],
  "env": {
    "NODE_ENV": "production"
  },
  "build": {
    "env": {
      "NEXT_PUBLIC_API_URL": "@api-url"
    }
  },
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    }
  ]
}

.vercelignore 示例​

# 忽略文件
node_modules
.git
.env.local
.DS_Store
*.log

# 文档
README.md
CHANGELOG.md

🛠️ 故障排查命令​

调试模式​

vercel --debug

查看详细输出​

vercel --prod --verbose

测试配置​

# 验证 vercel.json
vercel dev

清理缓存​

# 删除本地配置
rm -rf .vercel

# 重新链接
vercel link

💡 最佳实践​

1. 本地开发流程​

# 启动本地开发服务器（模拟 Vercel 环境）
vercel dev

# 或使用项目的开发命令
npm start

2. 预览部署测试​

# 部署到预览环境
vercel

# 获取预览 URL 测试
# 确认无误后再部署到生产
vercel --prod

3. 使用别名进行灰度发布​

# 部署新版本（预览）
vercel

# 设置临时域名测试
vercel alias <deployment-url> staging.example.com

# 确认无误后切换到生产
vercel alias <deployment-url> example.com

4. 自动化脚本​

#!/bin/bash
# deploy-production.sh

echo "🚀 开始生产部署..."

# 检查是否在 main 分支
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$BRANCH" != "main" ]; then
  echo "❌ 请在 main 分支上部署"
  exit 1
fi

# 确保代码是最新的
git pull origin main

# 安装依赖
npm ci

# 构建测试
npm run build

# 部署到 Vercel
vercel --prod --yes

echo "✅ 部署完成！"

🔐 Token 生成和使用​

生成 Token​

  1. 访问 https://vercel.com/account/tokens
  2. 点击 "Create Token"
  3. 输入 Token 名称
  4. 选择权限范围
  5. 复制生成的 Token

在 CI/CD 中使用​

# GitHub Actions
env:
  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

# 命令行使用
export VERCEL_TOKEN=your-token
vercel --prod --yes

📚 参考资源​

🎓 学习路径​

初级​

  1. ✅ 安装 CLI 并登录
  2. ✅ 部署第一个项目
  3. ✅ 查看部署列表和日志

中级​

  1. ✅ 配置环境变量
  2. ✅ 管理域名和别名
  3. ✅ 使用 vercel.json 配置

高级​

  1. ✅ CI/CD 集成
  2. ✅ 多环境部署策略
  3. ✅ 自定义部署脚本

提示: 使用 vercel --help 或 vercel <command> --help 查看任何命令的详细帮助信息。