mirror of
https://gitee.com/liuxioabin/fengketrade.git
synced 2026-04-17 12:57:32 +08:00
579 lines
12 KiB
Markdown
579 lines
12 KiB
Markdown
# Shopro 前端项目部署指南
|
||
|
||
## 概述
|
||
|
||
本文档描述如何将 Shopro uni-app 前端项目打包并部署到生产环境 `https://app.fengketrade.com`。
|
||
|
||
## 环境配置
|
||
|
||
### 生产环境配置已完成 ✅
|
||
|
||
`.env` 文件已配置：
|
||
```env
|
||
# 正式环境接口域名
|
||
SHOPRO_BASE_URL = https://app.fengketrade.com
|
||
|
||
# 开发环境接口域名
|
||
SHOPRO_DEV_BASE_URL = https://app.fengketrade.com
|
||
|
||
# 开发环境运行端口
|
||
SHOPRO_DEV_PORT = 3000
|
||
|
||
# 接口地址前缀
|
||
SHOPRO_API_PATH = /addons/shopro/
|
||
```
|
||
|
||
## 打包方法
|
||
|
||
### 方法一：使用 HBuilderX 打包（推荐）
|
||
|
||
这是 uni-app 官方推荐的打包方式，最稳定可靠。
|
||
|
||
#### 步骤 1: 准备 HBuilderX
|
||
|
||
1. **下载 HBuilderX**
|
||
- 官网：https://www.dcloud.io/hbuilderx.html
|
||
- 选择"正式版" → "标准版"即可
|
||
|
||
2. **安装必要插件**
|
||
- 启动 HBuilderX
|
||
- 工具 → 插件安装 → 搜索"uni-app编译"
|
||
- 安装"uni-app (Vue3)"编译器
|
||
|
||
#### 步骤 2: 打开项目
|
||
|
||
1. 文件 → 打开目录
|
||
2. 选择：`/Users/billy/Code/fengketrade.com/frontend`
|
||
3. 等待项目加载完成
|
||
|
||
#### 步骤 3: H5 打包
|
||
|
||
1. **发行到 H5**
|
||
- 发行 → 网站-H5手机版
|
||
- 或者点击菜单：发行 → 网站-PC Web或App（适用于宽屏应用）
|
||
|
||
2. **配置打包选项**
|
||
```
|
||
网站标题：风刻商城
|
||
网站域名：https://app.fengketrade.com
|
||
路由模式：hash（推荐）或 history
|
||
```
|
||
|
||
3. **点击"发行"**
|
||
- 等待编译完成
|
||
- 控制台会显示编译进度
|
||
|
||
4. **查看打包结果**
|
||
```
|
||
打包目录：/Users/billy/Code/fengketrade.com/frontend/unpackage/dist/build/h5
|
||
```
|
||
|
||
#### 步骤 4: 部署到服务器
|
||
|
||
```bash
|
||
cd /Users/billy/Code/fengketrade.com/frontend
|
||
|
||
# 压缩打包文件（排除 macOS 元数据）
|
||
tar --no-mac-metadata --no-xattrs --exclude='.DS_Store' \
|
||
-czf h5-dist.tar.gz -C unpackage/dist/build/h5 .
|
||
|
||
# 上传到服务器
|
||
scp h5-dist.tar.gz user@app.fengketrade.com:/tmp/
|
||
|
||
# 登录服务器
|
||
ssh user@app.fengketrade.com
|
||
|
||
# 解压到 Web 目录
|
||
cd /path/to/web/root
|
||
mkdir -p h5
|
||
tar -xzf /tmp/h5-dist.tar.gz -C h5/
|
||
|
||
# 设置权限
|
||
chown -R www-data:www-data h5/
|
||
chmod -R 755 h5/
|
||
```
|
||
|
||
### 方法二：使用命令行打包
|
||
|
||
如果已安装 uni-app CLI 工具，可以使用命令行打包。
|
||
|
||
#### 步骤 1: 安装 uni-app CLI
|
||
|
||
```bash
|
||
cd /Users/billy/Code/fengketrade.com/frontend
|
||
|
||
# 安装 uni-app 编译器（如果还没安装）
|
||
npm install -g @dcloudio/uvm
|
||
uvm
|
||
|
||
# 或直接安装依赖
|
||
npm install
|
||
```
|
||
|
||
#### 步骤 2: 添加构建脚本
|
||
|
||
编辑 `package.json`，添加以下脚本：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"dev:h5": "uni -p h5",
|
||
"build:h5": "uni build -p h5",
|
||
"build:h5:prod": "cross-env NODE_ENV=production uni build -p h5",
|
||
"prettier": "prettier --write \"{pages,sheep}/**/*.{js,json,tsx,css,less,scss,vue,html,md}\""
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 步骤 3: 执行打包
|
||
|
||
```bash
|
||
# 开发环境打包
|
||
npm run build:h5
|
||
|
||
# 生产环境打包（压缩优化）
|
||
npm run build:h5:prod
|
||
```
|
||
|
||
#### 步骤 4: 查看打包结果
|
||
|
||
```bash
|
||
ls -lh unpackage/dist/build/h5/
|
||
```
|
||
|
||
### 方法三：快速部署脚本（自动化）
|
||
|
||
创建自动化部署脚本。
|
||
|
||
#### 创建部署脚本
|
||
|
||
```bash
|
||
cat > deploy-frontend.sh << 'EOF'
|
||
#!/bin/bash
|
||
|
||
# 前端自动化部署脚本
|
||
# 作者: Billy
|
||
# 日期: 2025-01-17
|
||
|
||
set -e
|
||
|
||
echo "=== 前端部署脚本 ==="
|
||
|
||
# 配置
|
||
PROJECT_DIR="/Users/billy/Code/fengketrade.com/frontend"
|
||
BUILD_DIR="$PROJECT_DIR/unpackage/dist/build/h5"
|
||
SERVER_USER="your_user"
|
||
SERVER_HOST="app.fengketrade.com"
|
||
SERVER_PATH="/var/www/html/h5"
|
||
BACKUP_DIR="/var/www/backup"
|
||
|
||
# 颜色输出
|
||
GREEN='\033[0;32m'
|
||
RED='\033[0;31m'
|
||
YELLOW='\033[1;33m'
|
||
NC='\033[0m' # No Color
|
||
|
||
echo -e "${YELLOW}步骤 1: 检查环境...${NC}"
|
||
cd "$PROJECT_DIR"
|
||
|
||
if [ ! -d "node_modules" ]; then
|
||
echo -e "${YELLOW}安装依赖...${NC}"
|
||
npm install
|
||
fi
|
||
|
||
echo -e "${GREEN}✓ 环境检查完成${NC}"
|
||
|
||
echo -e "${YELLOW}步骤 2: 清理旧文件...${NC}"
|
||
rm -rf unpackage/dist/build/h5
|
||
|
||
echo -e "${YELLOW}步骤 3: 开始打包...${NC}"
|
||
# 如果有 HBuilderX CLI
|
||
if command -v cli &> /dev/null; then
|
||
cli publish --platform h5 --project "$PROJECT_DIR"
|
||
# 或使用 npm
|
||
elif [ -f "package.json" ]; then
|
||
npm run build:h5:prod || npm run build:h5
|
||
else
|
||
echo -e "${RED}✗ 找不到构建工具，请使用 HBuilderX 手动打包${NC}"
|
||
exit 1
|
||
fi
|
||
|
||
echo -e "${GREEN}✓ 打包完成${NC}"
|
||
|
||
echo -e "${YELLOW}步骤 4: 压缩文件...${NC}"
|
||
cd "$PROJECT_DIR"
|
||
tar --no-mac-metadata --no-xattrs --exclude='.DS_Store' \
|
||
-czf h5-dist-$(date +%Y%m%d-%H%M%S).tar.gz -C "$BUILD_DIR" .
|
||
|
||
ARCHIVE_NAME=$(ls -t h5-dist-*.tar.gz | head -1)
|
||
echo -e "${GREEN}✓ 压缩完成: $ARCHIVE_NAME${NC}"
|
||
|
||
echo -e "${YELLOW}步骤 5: 上传到服务器...${NC}"
|
||
scp "$ARCHIVE_NAME" "$SERVER_USER@$SERVER_HOST:/tmp/"
|
||
|
||
echo -e "${YELLOW}步骤 6: 部署到服务器...${NC}"
|
||
ssh "$SERVER_USER@$SERVER_HOST" << ENDSSH
|
||
set -e
|
||
|
||
# 创建备份
|
||
if [ -d "$SERVER_PATH" ]; then
|
||
echo "备份当前版本..."
|
||
sudo mkdir -p "$BACKUP_DIR"
|
||
sudo tar -czf "$BACKUP_DIR/h5-backup-\$(date +%Y%m%d-%H%M%S).tar.gz" \
|
||
-C "$SERVER_PATH" . || true
|
||
fi
|
||
|
||
# 解压新版本
|
||
echo "部署新版本..."
|
||
sudo mkdir -p "$SERVER_PATH"
|
||
sudo tar -xzf "/tmp/$ARCHIVE_NAME" -C "$SERVER_PATH"
|
||
|
||
# 设置权限
|
||
sudo chown -R www-data:www-data "$SERVER_PATH"
|
||
sudo chmod -R 755 "$SERVER_PATH"
|
||
|
||
# 清理临时文件
|
||
rm -f "/tmp/$ARCHIVE_NAME"
|
||
|
||
echo "部署完成！"
|
||
ENDSSH
|
||
|
||
echo -e "${GREEN}=== 部署成功！===${NC}"
|
||
echo -e "${GREEN}访问地址: https://app.fengketrade.com/h5${NC}"
|
||
|
||
# 清理本地临时文件
|
||
rm -f "$ARCHIVE_NAME"
|
||
EOF
|
||
|
||
chmod +x deploy-frontend.sh
|
||
```
|
||
|
||
#### 使用部署脚本
|
||
|
||
```bash
|
||
# 修改脚本中的服务器配置
|
||
vim deploy-frontend.sh
|
||
|
||
# 执行部署
|
||
./deploy-frontend.sh
|
||
```
|
||
|
||
## 部署后配置
|
||
|
||
### Nginx 配置
|
||
|
||
#### H5 项目配置
|
||
|
||
```nginx
|
||
# /etc/nginx/sites-available/app.fengketrade.com
|
||
|
||
server {
|
||
listen 80;
|
||
listen 443 ssl http2;
|
||
server_name app.fengketrade.com;
|
||
|
||
# SSL 证书配置
|
||
ssl_certificate /path/to/ssl/cert.pem;
|
||
ssl_certificate_key /path/to/ssl/key.pem;
|
||
|
||
# 强制 HTTPS
|
||
if ($scheme != "https") {
|
||
return 301 https://$server_name$request_uri;
|
||
}
|
||
|
||
# H5 前端
|
||
location /h5 {
|
||
alias /var/www/html/h5;
|
||
index index.html;
|
||
|
||
# 解决 Vue Router history 模式 404
|
||
try_files $uri $uri/ /h5/index.html;
|
||
|
||
# 静态资源缓存
|
||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
|
||
expires 30d;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
# HTML 不缓存
|
||
location ~* \.html$ {
|
||
expires -1;
|
||
add_header Cache-Control "no-cache, no-store, must-revalidate";
|
||
}
|
||
}
|
||
|
||
# API 代理到 PHP 后端
|
||
location /addons/shopro {
|
||
proxy_pass http://127.0.0.1:8080;
|
||
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;
|
||
}
|
||
|
||
# 建行测试页面
|
||
location /ccblife-demo.html {
|
||
alias /var/www/html/public/ccblife-demo.html;
|
||
}
|
||
|
||
# 静态资源
|
||
location /static {
|
||
alias /var/www/html/public;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 重启 Nginx
|
||
|
||
```bash
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重启服务
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
### Apache 配置（如果使用 Apache）
|
||
|
||
```apache
|
||
<VirtualHost *:443>
|
||
ServerName app.fengketrade.com
|
||
DocumentRoot /var/www/html
|
||
|
||
# SSL 配置
|
||
SSLEngine on
|
||
SSLCertificateFile /path/to/ssl/cert.pem
|
||
SSLCertificateKeyFile /path/to/ssl/key.pem
|
||
|
||
# H5 前端
|
||
Alias /h5 /var/www/html/h5
|
||
<Directory /var/www/html/h5>
|
||
Options -Indexes +FollowSymLinks
|
||
AllowOverride All
|
||
Require all granted
|
||
|
||
# Vue Router history 模式
|
||
RewriteEngine On
|
||
RewriteBase /h5
|
||
RewriteRule ^index\.html$ - [L]
|
||
RewriteCond %{REQUEST_FILENAME} !-f
|
||
RewriteCond %{REQUEST_FILENAME} !-d
|
||
RewriteRule . /h5/index.html [L]
|
||
</Directory>
|
||
|
||
# 静态资源缓存
|
||
<FilesMatch "\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$">
|
||
Header set Cache-Control "max-age=2592000, public"
|
||
</FilesMatch>
|
||
|
||
# HTML 不缓存
|
||
<FilesMatch "\.html$">
|
||
Header set Cache-Control "no-cache, no-store, must-revalidate"
|
||
</FilesMatch>
|
||
</VirtualHost>
|
||
```
|
||
|
||
## 部署检查清单
|
||
|
||
### 打包前检查
|
||
|
||
- [ ] ✅ `.env` 文件配置正确（生产环境域名）
|
||
- [ ] 检查 `manifest.json` 配置
|
||
- [ ] 移除开发环境的 console.log
|
||
- [ ] 移除调试工具（如 vconsole）
|
||
- [ ] 检查建行生活模块是否正确集成
|
||
|
||
### 打包检查
|
||
|
||
```bash
|
||
# 检查打包文件大小
|
||
du -sh unpackage/dist/build/h5
|
||
|
||
# 检查关键文件是否存在
|
||
ls -lh unpackage/dist/build/h5/index.html
|
||
ls -lh unpackage/dist/build/h5/static/
|
||
|
||
# 检查是否有 source map（生产环境应该移除）
|
||
find unpackage/dist/build/h5 -name "*.map"
|
||
```
|
||
|
||
### 部署后检查
|
||
|
||
```bash
|
||
# 1. 检查文件是否上传成功
|
||
ssh user@app.fengketrade.com "ls -lh /var/www/html/h5"
|
||
|
||
# 2. 检查权限
|
||
ssh user@app.fengketrade.com "ls -ld /var/www/html/h5"
|
||
|
||
# 3. 测试访问
|
||
curl -I https://app.fengketrade.com/h5/
|
||
|
||
# 4. 检查 API 接口
|
||
curl https://app.fengketrade.com/addons/shopro/ccbtest
|
||
```
|
||
|
||
### 功能测试
|
||
|
||
- [ ] 访问首页是否正常
|
||
- [ ] API 接口是否可以调用
|
||
- [ ] 建行生活模块是否正常
|
||
- [ ] 支付功能是否正常
|
||
- [ ] 图片资源是否加载
|
||
- [ ] 移动端适配是否正常
|
||
|
||
## 快速部署命令
|
||
|
||
### 本地到服务器一键部署
|
||
|
||
```bash
|
||
cd /Users/billy/Code/fengketrade.com/frontend
|
||
|
||
# 1. 打包（使用 HBuilderX 或命令行）
|
||
# HBuilderX: 发行 → 网站-H5手机版
|
||
|
||
# 2. 压缩
|
||
tar --no-mac-metadata --no-xattrs --exclude='.DS_Store' \
|
||
-czf h5-$(date +%Y%m%d-%H%M%S).tar.gz \
|
||
-C unpackage/dist/build/h5 .
|
||
|
||
# 3. 上传
|
||
ARCHIVE=$(ls -t h5-*.tar.gz | head -1)
|
||
scp $ARCHIVE user@app.fengketrade.com:/tmp/
|
||
|
||
# 4. 部署（在服务器上执行）
|
||
ssh user@app.fengketrade.com << 'EOF'
|
||
ARCHIVE=$(ls -t /tmp/h5-*.tar.gz | head -1)
|
||
sudo mkdir -p /var/www/html/h5
|
||
sudo tar -xzf $ARCHIVE -C /var/www/html/h5
|
||
sudo chown -R www-data:www-data /var/www/html/h5
|
||
sudo chmod -R 755 /var/www/html/h5
|
||
rm -f $ARCHIVE
|
||
echo "部署完成！"
|
||
EOF
|
||
|
||
# 5. 测试
|
||
curl -I https://app.fengketrade.com/h5/
|
||
```
|
||
|
||
## 回滚方案
|
||
|
||
### 快速回滚
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
cd /var/www/backup
|
||
|
||
# 查看备份
|
||
ls -lht h5-backup-*.tar.gz | head -5
|
||
|
||
# 回滚到指定版本
|
||
BACKUP_FILE="h5-backup-20250117-143000.tar.gz"
|
||
sudo rm -rf /var/www/html/h5/*
|
||
sudo tar -xzf $BACKUP_FILE -C /var/www/html/h5
|
||
sudo systemctl reload nginx
|
||
|
||
echo "已回滚到: $BACKUP_FILE"
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 打包优化
|
||
|
||
1. **启用 Gzip 压缩**（在 `vite.config.js`）
|
||
```javascript
|
||
import viteCompression from 'vite-plugin-compression';
|
||
|
||
export default {
|
||
plugins: [
|
||
viteCompression({
|
||
verbose: true,
|
||
disable: false,
|
||
threshold: 10240,
|
||
algorithm: 'gzip',
|
||
ext: '.gz'
|
||
})
|
||
]
|
||
}
|
||
```
|
||
|
||
2. **代码分割**
|
||
- uni-app 会自动进行代码分割
|
||
- 按页面分包加载
|
||
|
||
3. **图片优化**
|
||
- 压缩图片资源
|
||
- 使用 WebP 格式
|
||
- 启用懒加载
|
||
|
||
### CDN 配置
|
||
|
||
修改 `.env`：
|
||
```env
|
||
# 使用 CDN 加速静态资源
|
||
SHOPRO_STATIC_URL = https://cdn.fengketrade.com
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 打包后页面空白？
|
||
|
||
**原因**: 路径配置错误
|
||
|
||
**解决**:
|
||
```javascript
|
||
// manifest.json 中检查
|
||
{
|
||
"h5": {
|
||
"router": {
|
||
"mode": "hash", // 推荐使用 hash 模式
|
||
"base": "/h5/" // 根据实际部署路径调整
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Q: API 请求 404？
|
||
|
||
**原因**: 接口地址配置错误
|
||
|
||
**解决**: 检查 `.env` 中的 `SHOPRO_BASE_URL`
|
||
|
||
### Q: 静态资源 404？
|
||
|
||
**原因**: Nginx 配置问题
|
||
|
||
**解决**: 确保 Nginx 配置正确映射静态资源路径
|
||
|
||
### Q: 打包文件太大？
|
||
|
||
**解决**:
|
||
1. 移除无用的依赖
|
||
2. 启用代码压缩
|
||
3. 使用 CDN 加载大文件
|
||
4. 按需引入组件
|
||
|
||
## 监控和维护
|
||
|
||
### 访问日志
|
||
|
||
```bash
|
||
# Nginx 访问日志
|
||
sudo tail -f /var/log/nginx/access.log | grep "GET /h5"
|
||
|
||
# 错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
### 性能监控
|
||
|
||
使用浏览器开发者工具：
|
||
1. Network - 查看资源加载时间
|
||
2. Performance - 分析页面性能
|
||
3. Lighthouse - 综合评分
|
||
|
||
---
|
||
|
||
*文档版本: 1.0.0*
|
||
*最后更新: 2025-01-17*
|
||
*作者: Billy* |