shop-web/doc/部署指南.md

# 部署指南

## 部署概述

本文档详细描述了 MobVue 项目的部署流程和配置说明，涵盖开发环境、预发布环境和生产环境的部署步骤。

## 环境要求

### 服务器要求
- **操作系统**: Linux (推荐 Ubuntu 20.04+ 或 CentOS 7+)
- **Node.js**: 20.x 或 22+
- **Web 服务器**: Nginx 或 Apache
- **内存**: 至少 1GB RAM
- **存储**: 至少 10GB 可用空间

### 网络要求
- **域名**: 配置正确的域名和 SSL 证书
- **防火墙**: 开放 80 (HTTP) 和 443 (HTTPS) 端口
- **CDN**: 推荐使用 CDN 加速静态资源

## 环境配置

### 1. 环境变量

#### 开发环境 (.env.development)
```env
# 开发环境配置
VITE_BASE_URL=https://apifoxmock.com/m1/2930465-2145633-default
VITE_PUBLIC_PATH=/
VITE_ROUTER_HISTORY=hash
```

#### 预发布环境 (.env.staging)
```env
# 预发布环境配置
VITE_BASE_URL=https://staging-api.example.com
VITE_PUBLIC_PATH=/
VITE_ROUTER_HISTORY=hash
```

#### 生产环境 (.env.production)
```env
# 生产环境配置
VITE_BASE_URL=https://api.example.com
VITE_PUBLIC_PATH=/
VITE_ROUTER_HISTORY=hash
```

### 2. 微信配置

#### 微信公众号配置
- **AppID**: 微信公众号应用 ID
- **AppSecret**: 微信公众号应用密钥
- **回调域名**: 配置为部署的域名

#### 企业微信配置
- **CorpID**: 企业微信企业 ID
- **AgentID**: 企业微信应用 ID
- **Secret**: 企业微信应用密钥
- **回调域名**: 配置为部署的域名

## 构建流程

### 1. 开发环境构建
```bash
# 安装依赖
pnpm i

# 启动开发服务器
pnpm dev
```

### 2. 预发布环境构建
```bash
# 构建预发布版本
pnpm build:staging

# 构建输出目录: dist/
```

### 3. 生产环境构建
```bash
# 构建生产版本
pnpm build

# 构建输出目录: dist/
```

### 构建优化
- **代码分割**: Vue 相关库独立打包
- **压缩优化**: 移除 console 和 debugger
- **浏览器兼容**: 传统浏览器支持
- **资源优化**: 图片和字体文件压缩

## 部署方式

### 1. 静态文件部署

#### Nginx 配置示例
```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 配置
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;

    # 静态文件服务
    root /var/www/mobvue/dist;
    index index.html;

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # 缓存配置
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass https://api.example.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

#### Apache 配置示例
```apache
<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/mobvue/dist

    # 重定向到 HTTPS
    Redirect permanent / https://your-domain.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName your-domain.com
    DocumentRoot /var/www/mobvue/dist

    # SSL 配置
    SSLEngine on
    SSLCertificateFile /path/to/certificate.crt
    SSLCertificateKeyFile /path/to/private.key

    # SPA 路由支持
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]

    # 缓存配置
    <FilesMatch "\.(js|css|png|jpg|jpeg|gif|ico|svg)$">
        ExpiresActive On
        ExpiresDefault "access plus 1 year"
        Header append Cache-Control "public, immutable"
    </FilesMatch>
</VirtualHost>
```

### 2. Docker 部署

#### Dockerfile
```dockerfile
# 构建阶段
FROM node:20-alpine AS builder

WORKDIR /app

# 复制 package.json 和 lock 文件
COPY package.json pnpm-lock.yaml ./

# 安装依赖
RUN npm install -g pnpm && pnpm i

# 复制源代码
COPY . .

# 构建应用
RUN pnpm build

# 生产阶段
FROM nginx:alpine

# 复制构建结果
COPY --from=builder /app/dist /usr/share/nginx/html

# 复制 Nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 暴露端口
EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

#### docker-compose.yml
```yaml
version: '3.8'

services:
  mobvue:
    build: .
    ports:
      - "80:80"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

  # 可选：添加反向代理
  nginx-proxy:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx-proxy.conf:/etc/nginx/conf.d/default.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - mobvue
    restart: unless-stopped
```

### 3. 云平台部署

#### Vercel 部署
1. 连接 GitHub 仓库
2. 配置环境变量
3. 自动部署

#### Netlify 部署
1. 连接 Git 仓库
2. 构建命令: `pnpm build`
3. 发布目录: `dist`
4. 配置重定向规则

#### 阿里云/腾讯云部署
1. 上传构建文件到对象存储
2. 配置 CDN 加速
3. 配置域名和 SSL

## 部署检查清单

### 构建前检查
- [ ] 环境变量配置正确
- [ ] 依赖安装完成
- [ ] 代码 lint 通过
- [ ] 单元测试通过

### 部署前检查
- [ ] 构建产物完整
- [ ] 静态资源路径正确
- [ ] API 接口可访问
- [ ] 路由配置正确

### 部署后验证
- [ ] 首页可正常访问
- [ ] 路由跳转正常
- [ ] API 调用正常
- [ ] 移动端适配正常
- [ ] 微信登录正常
- [ ] 图片资源加载正常

## 监控和维护

### 1. 性能监控
- **Web Vitals**: 监控核心性能指标
- **错误监控**: 使用 Sentry 或类似工具
- **用户行为分析**: 使用 Google Analytics

### 2. 日志管理
- **访问日志**: Nginx 访问日志
- **错误日志**: 应用错误日志
- **API 日志**: 后端接口调用日志

### 3. 备份策略
- **代码备份**: Git 仓库备份
- **数据库备份**: 定期备份数据库
- **配置文件备份**: 环境配置备份

## 故障排除

### 常见问题

#### 1. 白屏问题
- 检查静态资源路径
- 验证路由配置
- 查看浏览器控制台错误

#### 2. API 调用失败
- 检查网络连接
- 验证 API 地址配置
- 查看跨域配置

#### 3. 微信登录失败
- 检查回调域名配置
- 验证 AppID 和 Secret
- 查看微信授权日志

#### 4. 移动端适配问题
- 测试不同设备尺寸
- 检查 viewport 配置
- 验证 CSS 媒体查询

### 调试工具
- **浏览器 DevTools**: 调试前端代码
- **网络监控**: 检查 API 请求
- **移动端模拟**: 测试移动端体验
- **性能分析**: 分析页面性能

## 安全考虑

### 1. 网络安全
- 使用 HTTPS 加密传输
- 配置 CSP 安全策略
- 启用 HSTS 强制 HTTPS

### 2. 应用安全
- 输入验证和过滤
- XSS 防护
- CSRF 防护

### 3. 数据安全
- 敏感信息加密存储
- 定期安全扫描
- 访问权限控制

## 版本管理

### 1. 版本号规范
- 遵循语义化版本规范 (SemVer)
- 主版本号.次版本号.修订版本号
- 预发布版本使用标签 (如: 1.0.0-beta.1)

### 2. 发布流程
1. 功能开发和测试
2. 预发布环境验证
3. 生产环境部署
4. 监控和反馈

### 3. 回滚策略
- 保留历史版本构建
- 快速回滚到稳定版本
- 数据库版本兼容性检查

## 附录

### 常用命令
```bash
# 开发
pnpm dev

# 构建
pnpm build
pnpm build:staging

# 代码检查
pnpm lint
pnpm test

# 依赖管理
pnpm i
pnpm update
```

### 配置文件说明
- `vite.config.ts`: Vite 构建配置
- `uno.config.ts`: UnoCSS 配置
- `tsconfig.json`: TypeScript 配置
- `eslint.config.js`: ESLint 配置

### 相关文档
- [Vue 3 官方文档](https://vuejs.org/)
- [Vite 官方文档](https://vitejs.dev/)
- [Vant 官方文档](https://vant-ui.github.io/vant/)
- [UnoCSS 官方文档](https://unocss.dev/)