# 部署说明文档

## 🚀 打包部署流程

### 1. 打包前准备

确保已安装依赖：
```bash
npm install
```

### 2. 执行打包

```bash
npm run build
```

打包完成后，会在项目根目录生成 `dist` 文件夹。

### 3. 缓存控制策略

本项目已配置完善的缓存控制策略，避免浏览器缓存导致更新不生效：

#### ✅ 已配置的缓存方案

1. **文件名 Hash 化**（`vite.config.js` 已配置）
   - 所有 JS、CSS、图片等资源文件名都会带上 hash 值
   - 例如：`index.a1b2c3d4.js`、`style.e5f6g7h8.css`
   - 每次构建后，修改过的文件 hash 会变化，自动避免缓存

2. **HTML 文件不缓存**
   - `index.html` 设置为不缓存，每次都会获取最新版本
   - 通过服务器配置实现（见下方）

#### 📝 服务器配置

##### Apache 服务器（使用 .htaccess）

项目已包含 `public/.htaccess` 文件，打包后会自动复制到 `dist` 目录。

##### Nginx 服务器

参考项目根目录的 `nginx.conf.example` 文件，配置说明：

```nginx
# HTML 文件不缓存
location / {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

# 静态资源长期缓存
location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
```

### 4. 部署步骤

#### 方法一：手动部署

1. 将 `dist` 目录下的所有文件上传到服务器
2. 配置服务器（Apache 或 Nginx）
3. 重启服务器

#### 方法二：使用 FTP/SFTP

```bash
# 上传 dist 目录到服务器
scp -r dist/* user@your-server:/var/www/html/
```

#### 方法三：使用 Docker（可选）

创建 `Dockerfile`：
```dockerfile
FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf.example /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### 5. 更新部署注意事项

#### ⚠️ 每次更新部署时：

1. **清理旧文件**
   ```bash
   # 删除服务器上的旧文件
   rm -rf /var/www/html/*
   ```

2. **上传新文件**
   ```bash
   # 上传新的 dist 文件
   scp -r dist/* user@your-server:/var/www/html/
   ```

3. **清理服务器缓存**（如果使用了缓存服务器）
   ```bash
   # Nginx
   nginx -s reload
   
   # Apache
   systemctl reload apache2
   ```

4. **通知用户清理浏览器缓存**（可选）
   - 可以在系统中添加版本提示
   - 或者使用 Service Worker 强制更新

### 6. 验证部署

部署完成后，验证步骤：

1. **清除浏览器缓存**
   - Chrome: `Ctrl + Shift + Delete` 或 `Cmd + Shift + Delete`
   - 或使用隐身模式访问

2. **检查文件版本**
   - 打开浏览器开发者工具（F12）
   - 查看 Network 标签
   - 确认 JS/CSS 文件名带有新的 hash 值

3. **检查 HTML 缓存**
   - 查看 `index.html` 的响应头
   - 确认 `Cache-Control: no-cache`

### 7. 常见问题

#### Q1: 用户反馈看到的还是旧版本？

**解决方案：**
1. 确认服务器配置正确（.htaccess 或 nginx 配置）
2. 清理 CDN 缓存（如果使用了 CDN）
3. 通知用户强制刷新（Ctrl + F5 或 Cmd + Shift + R）

#### Q2: 静态资源 404 错误？

**解决方案：**
1. 检查资源路径配置
2. 确认 `vite.config.js` 中的 `base` 配置正确
3. 检查服务器的静态文件路径

#### Q3: SPA 路由刷新 404？

**解决方案：**
- Apache: 确保 `.htaccess` 中的 rewrite 规则生效
- Nginx: 确保配置了 `try_files $uri $uri/ /index.html;`

### 8. 自动化部署（可选）

#### 使用 GitHub Actions

创建 `.github/workflows/deploy.yml`：

```yaml
name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy to server
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
          REMOTE_USER: ${{ secrets.REMOTE_USER }}
          TARGET: /var/www/html/
```

### 9. 性能优化建议

1. **启用 Gzip/Brotli 压缩**
2. **使用 CDN 加速静态资源**
3. **配置 HTTP/2**
4. **启用 HTTPS**

## 📞 技术支持

如有部署问题，请联系技术团队。