# 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. 环境检查

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

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

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

# 检查项目依赖
cd frontend
npm install
```

### 2. 本地测试

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

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

# 本地开发测试
npm run dev

# 构建测试
npm run build

# 预览构建结果
npm run preview
```

### 3. 环境变量配置

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

## 部署方法

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

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

#### 1. 推送代码到 Git 仓库

```bash
# 初始化 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](https://vercel.com/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

```bash
npm i -g vercel
```

#### 2. 登录 Vercel

```bash
vercel login
```

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

#### 3. 初始化项目

```bash
# 在 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. 设置环境变量

```bash
# 添加生产环境变量
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. 部署到生产环境

```bash
vercel --prod
```

### 方法三：通过 GitHub Actions + Vercel

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

```yaml
# .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` 中已经包含了基本的缓存配置。如需更详细的缓存控制：

```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

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

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

#### 使用浏览器性能监控

```javascript
// 在应用中添加性能监控
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. 错误处理和告警

#### 配置错误监控

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

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

## 故障排除

### 常见问题及解决方案

#### 1. 部署失败

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

**解决方案**:
```bash
# 本地运行构建命令，检查具体错误
npm run build

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

**常见错误**:

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

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

#### 2. 环境变量问题

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

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

```javascript
// 验证环境变量
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` 中的路由配置

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

#### 4. API 请求失败

**问题**: 后端 API 请求失败

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

```javascript
// 添加请求重试机制
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. 代码分割

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

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

#### 2. 图片优化

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

#### 3. 缓存策略

```javascript
// 启用 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 官方文档](https://vercel.com/docs)
2. 检查项目部署日志
3. 使用 Vercel CLI 进行调试: `vercel logs`

祝你部署顺利！🚀