196 lines
4.3 KiB
Markdown
196 lines
4.3 KiB
Markdown
# 部署说明文档
|
||
|
||
## 🚀 打包部署流程
|
||
|
||
### 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**
|
||
|
||
## 📞 技术支持
|
||
|
||
如有部署问题，请联系技术团队。
|
||
|
||
|