521 lines
11 KiB
Markdown
521 lines
11 KiB
Markdown
# 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`
|
||
|
||
祝你部署顺利！🚀 |