Vercel 部署指南

Vercel 是现代化的前端部署平台，支持静态站点和多种前端框架。VUP 项目提供开箱即用的部署方式。

部署方式

方式一：本地命令部署

在项目根目录执行：

# 生产部署
pnpm deploy:prod

# 预览部署
pnpm deploy:preview

方式二：GitHub 自动部署

1. 连接仓库

   • 在 Vercel 控制台导入 GitHub 仓库
   • 项目根目录选择仓库根目录

2. 自动部署规则

   • 推送到 main 分支自动发布生产环境
   • 推送到其他分支自动生成预览链接

项目配置

项目根目录已包含 vercel.json，推荐按基座模板保持以下结构：

{
  "buildCommand": "cd apps/{project_name} && pnpm build",
  "outputDirectory": "apps/{project_name}/.output",
  "installCommand": "pnpm install --no-frozen-lockfile",
  "devCommand": "cd apps/{project_name} && pnpm dev",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=0, must-revalidate"
        }
      ]
    }
  ]
}

注意：请将 {project_name} 替换为 apps/ 下实际应用目录名，例如 homepage 或 my-app。

环境变量

本地开发

创建 .env.local：

# .env.local
VITE_API_BASE=https://api.example.com
VITE_APP_TITLE=My App

生产环境

在 Vercel 控制台设置：

1. 进入项目设置
2. 打开 "Environment Variables"
3. 添加变量并选择环境（Production / Preview / Development）

也可使用 CLI：

vercel env add VITE_API_BASE production
vercel env add VITE_APP_TITLE production
vercel env ls

自定义域名

1. 在 Vercel 控制台进入项目
2. 打开 "Settings" > "Domains"
3. 添加自定义域名
4. 按提示配置 DNS 记录

常见问题

构建失败

排查顺序：

1. 检查 apps/{project_name}/package.json 的 build 脚本
2. 确认依赖安装完整
3. 检查环境变量是否配置
4. 查看 Vercel 构建日志

刷新路由 404

确保存在 SPA 重写规则：

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

环境变量未生效

1. Vite 项目变量名应以 VITE_ 开头
2. 修改变量后重新触发部署
3. 检查变量是否配置在正确环境（Production/Preview）

最佳实践

1. 保持 vercel.json 与基座模板一致，避免混用旧版 version/builds/routes 写法
2. 每个应用独立指定 buildCommand 与 outputDirectory
3. 通过 Preview 部署先验证，再发布 Production

相关资源

• Vercel 官方文档
• Vercel CLI 文档
• 环境变量管理