deotalandAi/apps/frontend/docs/vercel-deployment-guide.md

Vercel 部署完整指南

项目概述

本项目是一个基于 Vue3 + Vite 构建的现代化前端应用，集成 AI 功能、支付系统和响应式设计。部署到 Vercel 可获得以下优势：

• 🚀 全球 CDN 加速
• ⚡ 自动 HTTPS
• 🔄 自动部署和回滚
• 📊 实时性能监控
• 🌍 自定义域名支持

技术栈

• 前端框架: Vue 3 (Composition API)
• 构建工具: Vite 7.2.2
• UI 组件: Element Plus
• 路由: Vue Router 4
• 状态管理: Pinia
• 国际化: Vue I18n
• 支付: Stripe
• AI 服务: Google AI API

部署前准备

1. 环境检查

确保你的本地环境满足以下要求：

# 检查 Node.js 版本（推荐 >= 18.0.0）
node --version

# 检查 npm 版本（推荐 >= 9.0.0）
npm --version

# 检查项目依赖
cd frontend
npm install

2. 本地测试

在部署前，先在本地验证项目正常运行：

# 安装依赖（如果还未安装）
npm install

# 本地开发测试
npm run dev

# 构建测试
npm run build

# 预览构建结果
npm run preview

3. 环境变量配置

根据 docs/environment-setup.md 指南，配置必要环境变量。

部署方法

方法一：通过 Git 集成自动部署（推荐）

这是最简单和推荐的部署方式：

1. 推送代码到 Git 仓库

# 初始化 Git（如果还未初始化）
git init
git add .
git commit -m "Initial commit"

# 添加远程仓库（替换为你的仓库地址）
git remote add origin https://github.com/your-username/your-repo.git

# 推送代码
git push -u origin main

2. 在 Vercel 中导入项目

1. 访问 Vercel Dashboard
2. 点击 "New Project"
3. 选择 "Import Git Repository"
4. 选择你的 Git 提供商（GitHub/GitLab/Bitbucket）
5. 找到你的仓库并点击 "Import"

3. 配置项目设置

在项目导入页面配置以下设置：

Project Name: deotaland-ai (或你喜欢的名称)
Framework Preset: Vite
Root Directory: frontend (如果你的项目在子目录中)
Build Command: npm run build
Output Directory: dist
Install Command: npm install

4. 配置环境变量

在 "Environment Variables" 部分添加：

Name	Value	Environment
VITE_GOOGLE_API_KEY	你的 Google API 密钥	Production, Preview, Development
VITE_APP_BASE_API	你的 API 基础地址	根据需要设置
VITE_STRIPE_PUBLISHABLE_KEY	你的 Stripe 公钥	Production, Preview, Development
NODE_ENV	production	Production

5. 部署项目

点击 "Deploy" 按钮，Vercel 将开始构建和部署你的项目。

方法二：通过 Vercel CLI 部署

1. 安装 Vercel CLI

npm i -g vercel

2. 登录 Vercel

vercel login

按照提示使用你的 GitHub、GitLab 或 Email 账户登录。

3. 初始化项目

# 在 frontend 目录中
cd frontend
vercel

# 按提示配置：
# ? Set up and deploy "~/your-project/frontend"? [Y/n] y
# ? Which scope do you want to deploy to? 选择你的账户
# ? Link to existing project? [y/N] n
# ? What's your project's name? deotaland-ai
# ? In which directory is your code located? ./
# ? Want to override the settings? [y/N] n

4. 设置环境变量

# 添加生产环境变量
vercel env add VITE_GOOGLE_API_KEY production
vercel env add VITE_APP_BASE_API production
vercel env add VITE_STRIPE_PUBLISHABLE_KEY production

5. 部署到生产环境

vercel --prod

方法三：通过 GitHub Actions + Vercel

如果你想要更高级的 CI/CD 配置，可以创建一个 GitHub Actions 工作流：

# .github/workflows/vercel.yml
name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
          cache-dependency-path: 'frontend/package-lock.json'
      
      - name: Install dependencies
        run: npm ci
        working-directory: frontend
      
      - name: Build project
        run: npm run build
        working-directory: frontend
        env:
          VITE_GOOGLE_API_KEY: ${{ secrets.VITE_GOOGLE_API_KEY }}
          VITE_APP_BASE_API: ${{ secrets.VITE_APP_BASE_API }}
          VITE_STRIPE_PUBLISHABLE_KEY: ${{ secrets.VITE_STRIPE_PUBLISHABLE_KEY }}
      
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}
          working-directory: frontend
          vercel-args: '--prod'

部署后配置

1. 自定义域名（可选）

如果你有自己的域名，可以配置到 Vercel：

在 Vercel Dashboard 中配置：

1. 拆件项目设置 → Domains
2. 添加你的域名
3. 按照指示配置 DNS 记录

DNS 配置示例：

对于 your-domain.com：

Type: A
Name: @
Value: 76.76.19.61

Type: CNAME
Name: www
Value: cname.vercel-dns.com

2. HTTPS 证书

Vercel 会自动为你的域名配置 Let's Encrypt SSL 证书，通常在几分钟内生效。

3. 性能优化配置

启用 Analytics

在 Vercel Dashboard 中启用 Web Analytics 以监控性能：

1. 拆件项目 → Analytics
2. 启用 Web Analytics

配置缓存策略

在 vercel.json 中已经包含了基本的缓存配置。如需更详细的缓存控制：

{
  "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"
        }
      ]
    }
  ]
}

监控和维护

1. 查看部署日志

在 Vercel Dashboard 中查看部署状态和日志：

1. 拆件项目 → Deployments
2. 点击任意部署查看详细日志

2. 监控应用性能

使用 Vercel Analytics

// 在 main.js 中添加
import { inject } from 'vue'

export default {
  setup() {
    // 页面性能监控
    if (import.meta.env.PROD) {
      inject('analytics', () => {
        // 你的分析代码
      })
    }
  }
}

使用浏览器性能监控

// 在应用中添加性能监控
export const performanceMonitor = {
  trackPageLoad: () => {
    if (typeof window !== 'undefined' && window.performance) {
      const navigation = performance.getEntriesByType('navigation')[0]
      console.log('Page Load Time:', navigation.loadEventEnd - navigation.loadEventStart)
    }
  },
  
  trackAPICall: (url, duration) => {
    console.log(`API Call to ${url} took ${duration}ms`)
  }
}

3. 错误处理和告警

配置错误监控

// 全局错误处理
window.addEventListener('error', (event) => {
  console.error('Global error:', event.error)
  // 发送错误到监控服务
})

window.addEventListener('unhandledrejection', (event) => {
  console.error('Unhandled promise rejection:', event.reason)
  // 发送错误到监控服务
})

故障排除

常见问题及解决方案

1. 部署失败

问题: 构建过程中出现错误

解决方案:

# 本地运行构建命令，检查具体错误
npm run build

# 查看详细错误信息
npm run build -- --debug

常见错误:

• 依赖安装失败: 检查 package.json 中的依赖版本
• 构建超时: 优化构建配置，减少不必要的依赖
• 内存不足: 在 vercel.json 中增加构建内存限制

{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "maxLambdaSize": "50mb"
      }
    }
  ]
}

2. 环境变量问题

问题: 环境变量未正确加载

解决方案:

1. 检查变量名是否以 VITE_ 开头
2. 确认在正确的环境中设置了变量
3. 重新部署应用

// 验证环境变量
console.log('Environment variables check:', {
  googleApiKey: !!import.meta.env.VITE_GOOGLE_API_KEY,
  apiBase: import.meta.env.VITE_APP_BASE_API,
  stripeKey: !!import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY
})

3. 路由 404 错误

问题: 直接访问路由路径时出现 404

解决方案: 检查 vercel.json 中的路由配置

{
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

4. API 请求失败

问题: 后端 API 请求失败

解决方案:

1. 检查 CORS 配置
2. 验证 API 基础地址
3. 确认 API 服务正常运行

// 添加请求重试机制
const apiClient = axios.create({
  baseURL: import.meta.env.VITE_APP_BASE_API,
  timeout: 10000,
  retries: 3
})

// 请求拦截器
apiClient.interceptors.response.use(
  response => response,
  error => {
    if (error.code === 'NETWORK_ERROR') {
      // 网络错误处理
      console.error('Network error:', error)
    }
    return Promise.reject(error)
  }
)

性能优化

1. 代码分割

已经配置了手动代码分割，检查效果：

// 动态导入示例
const ModelViewer = defineAsyncComponent(() => 
  import('@/components/ThreeModelViewer/ModelViewer.vue')
)

2. 图片优化

// 使用响应式图片
<img 
  :src="`${imageUrl}?w=${width}&q=${quality}`"
  :srcset="generateSrcSet(imageUrl)"
  :sizes="sizes"
  loading="lazy"
  alt="Description"
/>

3. 缓存策略

// 启用 Service Worker（如果需要）
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js')
}

持续集成和部署

自动部署触发条件

Vercel 支持以下触发条件：

• 推送到分支: 自动部署到预览环境
• 推送到主分支: 自动部署到生产环境
• Pull Request: 创建预览部署
• 手动部署: 通过 Dashboard 或 CLI

分支策略建议

main/production  -> 生产环境
develop          -> 预览环境
feature/*        -> 功能分支预览

总结

通过本指南，你应该能够成功将 Vue3 前端应用部署到 Vercel。记住：

1. 测试优先: 部署前确保本地测试通过
2. 环境变量: 正确配置所有必需的环境变量
3. 监控: 设置适当的监控和告警
4. 性能: 持续优化加载速度和用户体验
5. 安全: 定期更新依赖和安全配置

如果遇到问题，可以：

1. 查看 Vercel 官方文档
2. 检查项目部署日志
3. 使用 Vercel CLI 进行调试: vercel logs

祝你部署顺利！🚀