fengketrade/doc/frontend-deployment-guide.md

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