cpzs-frontend/lottery-app/DEPLOY.md

部署说明文档

🚀 打包部署流程

1. 打包前准备

确保已安装依赖：

npm install

2. 执行打包

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 文件，配置说明：

# 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

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

方法三：使用 Docker（可选）

创建 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. 清理旧文件

   # 删除服务器上的旧文件
   rm -rf /var/www/html/*
   

2. 上传新文件

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

3. 清理服务器缓存（如果使用了缓存服务器）

   # 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：

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

📞 技术支持

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