# 🌐 多平台构建完全指南

## 📋 支持的平台

✅ **Android** - arm64-v8a / armeabi-v7a / x86_64
✅ **Windows** - x64
✅ **macOS** - Universal (Intel + Apple Silicon)
✅ **Linux** - x64

---

## 🚀 快速开始

### 方法 1: 构建所有平台（推荐）

1. 打开 GitHub Actions 页面
2. 选择 **Build Multi-Platform**
3. 点击 **Run workflow**
4. 配置参数：

```yaml
构建类型: release
API 域名: api.maodag.top
OSS 地址 1-4: 使用默认值
构建平台: android,windows,macos,linux  # 构建所有平台
```

5. 点击 **Run workflow** 开始

---

### 方法 2: 仅构建指定平台

**场景：** 只需要 Android 和 Windows 版本

```yaml
构建平台: android,windows  # 只构建这两个平台
```

**可选值：**
- `android` - 仅 Android
- `windows` - 仅 Windows  
- `macos` - 仅 macOS
- `linux` - 仅 Linux
- `android,windows` - Android + Windows
- `android,windows,macos,linux` - 全部平台

---

## ⏱️ 构建时间估算

| 平台 | 时间 | 说明 |
|-----|------|-----|
| **libcore** | 10-15分钟 | Android 依赖 |
| **Android** | 15-20分钟 | 3个架构APK |
| **Windows** | 10-15分钟 | x64可执行文件 |
| **macOS** | 15-20分钟 | Universal应用 |
| **Linux** | 10-15分钟 | x64可执行文件 |
| **总计（全平台）** | **60-85分钟** | 并行构建 |

---

## 📦 构建产物

### Android

```
BearVPN-android-arm64-v8a-release-20251027-abc1234.apk     (推荐)
BearVPN-android-armeabi-v7a-release-20251027-abc1234.apk   (老设备)
BearVPN-android-x86_64-release-20251027-abc1234.apk        (模拟器)
```

**安装：** 直接点击APK安装

---

### Windows

```
BearVPN-windows-x64-release-20251027-abc1234.zip
```

**内容结构：**
```
BearVPN.exe                    # 主程序
flutter_windows.dll            # Flutter运行时
data/                         # 资源文件
```

**运行：**
1. 解压 ZIP 文件
2. 双击 `BearVPN.exe` 运行
3. 如提示缺少依赖，安装 [VC++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe)

---

### macOS

```
BearVPN-macos-release-20251027-abc1234.zip
```

**内容：**
```
BearVPN.app                   # 应用程序包（Universal）
```

**安装：**
1. 解压 ZIP 文件
2. 将 `BearVPN.app` 拖到 **应用程序** 文件夹
3. 首次运行右键点击 → 打开（绕过 Gatekeeper）

**支持架构：**
- Intel (x86_64)
- Apple Silicon (arm64)

---

### Linux

```
BearVPN-linux-x64-release-20251027-abc1234.tar.gz
```

**内容结构：**
```
bearvpn                       # 可执行文件
lib/                          # 共享库
data/                         # 资源文件
```

**运行：**
```bash
# 1. 解压
tar -xzf BearVPN-linux-x64-release-*.tar.gz
cd bundle

# 2. 添加执行权限
chmod +x bearvpn

# 3. 运行
./bearvpn
```

**依赖要求：**
- GTK+ 3
- libstdc++12

**安装依赖（Ubuntu/Debian）：**
```bash
sudo apt-get install libgtk-3-0 libstdc++6
```

**安装依赖（Fedora/RHEL）：**
```bash
sudo dnf install gtk3 libstdc++
```

---

## 🔧 配置说明

### 所有平台通用配置

| 参数 | 默认值 | 说明 |
|-----|-------|------|
| **构建类型** | `release` | debug 或 release |
| **API 域名** | `api.maodag.top` | 后端服务器 |
| **OSS 地址 1** | 香港 CDN | 配置文件源 |
| **OSS 地址 2** | 东京 CDN | 备用源 |
| **OSS 地址 3** | 首尔 CDN | 备用源 |
| **OSS 地址 4** | 新加坡 CDN | 备用源 |
| **构建平台** | `android,windows,macos,linux` | 选择平台 |

---

## 📥 下载构建产物

### 从 Actions 页面下载

1. 打开运行记录
2. 滚动到 **Artifacts** 区域
3. 下载对应平台：
   - `android-apk` - Android APK (所有架构)
   - `windows-x64` - Windows 可执行程序
   - `macos-app` - macOS 应用
   - `linux-x64` - Linux 可执行程序

### 从 Releases 下载（推送标签时）

1. 访问 Releases 页面
2. 选择版本
3. 在 Assets 中下载对应平台文件

---

## 🎯 使用场景

### 场景 1: 开发测试（仅 Android）

```yaml
构建类型: debug
构建平台: android
API 域名: api.test.com
```

**优点：** 快速，约20分钟

---

### 场景 2: 正式发布（全平台）

```yaml
构建类型: release
构建平台: android,windows,macos,linux
API 域名: api.maodag.top
```

**优点：** 一次构建，覆盖所有用户

---

### 场景 3: 仅桌面平台

```yaml
构建类型: release
构建平台: windows,macos,linux
```

**用途：** 桌面版更新

---

## 🐛 常见问题

### Q1: Windows 构建失败 - "7z command not found"

**原因：** Windows runner 默认有 7z

**解决：** 检查构建日志，可能是其他错误

---

### Q2: macOS 构建失败 - "Code signing required"

**原因：** Release 构建需要签名

**解决方案：**

**方法 1：** 使用 debug 构建（测试用）

**方法 2：** 配置签名证书（生产用）
```yaml
# 在 Secrets 中添加
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
MACOS_KEYCHAIN_PASSWORD
PROVISIONING_PROFILE_BASE64
```

---

### Q3: Linux 运行时提示缺少库

**错误：**
```
error while loading shared libraries: libgtk-3.so.0
```

**解决：**
```bash
sudo apt-get update
sudo apt-get install libgtk-3-0
```

---

### Q4: 如何只更新某个平台？

**方法 1：** 手动触发指定平台
```yaml
构建平台: android  # 只构建 Android
```

**方法 2：** 创建平台专用 workflow（推荐）

---

### Q5: 构建时间太长怎么办？

**优化方案：**

1. **仅构建需要的平台**
   ```yaml
   构建平台: android  # 而不是全部
   ```

2. **使用缓存**（已配置）
   - Flutter SDK 缓存
   - Gradle 缓存
   - Go modules 缓存

3. **分批构建**
   - 白天构建 Android/Windows
   - 晚上构建 macOS/Linux

---

## 💡 高级用法

### 技巧 1: 矩阵构建多个配置

修改 workflow:

```yaml
strategy:
  matrix:
    api_domain: ['api.prod.com', 'api.test.com']
    platform: ['android', 'windows', 'macos', 'linux']
```

**效果：** 生成 8 个版本（2域名 × 4平台）

---

### 技巧 2: 定时自动构建

添加到 workflow:

```yaml
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点（UTC）
```

---

### 技巧 3: 构建完成通知

添加 Telegram 通知:

```yaml
- name: 📢 通知
  run: |
    curl -X POST "https://api.telegram.org/bot${{ secrets.TG_BOT_TOKEN }}/sendMessage" \
      -d chat_id=${{ secrets.TG_CHAT_ID }} \
      -d text="✅ 多平台构建完成！"
```

---

## 📊 构建并行示意图

```
libcore (15min)
    ↓
    ├─→ Android (20min) ─┐
    ├─→ Windows (15min) ─┤
    ├─→ macOS (20min)   ─┼─→ Release (2min)
    └─→ Linux (15min)   ─┘

总时间: 约 35-40分钟（并行）
如果串行: 约 85分钟
```

---

## 🔐 安全建议

### Release 版本签名

**Android:**
```yaml
# Secrets 配置
KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD
```

**macOS:**
```yaml
# Secrets 配置
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
```

**Windows:**
```yaml
# Secrets 配置
WINDOWS_CERTIFICATE_BASE64
WINDOWS_CERTIFICATE_PASSWORD
```

---

## 📞 需要帮助？

- 查看 [GitHub Actions 文档](https://docs.github.com/actions)
- 查看 [Flutter 桌面支持](https://docs.flutter.dev/desktop)
- 提交 Issue

---

**版本:** 1.0.0  
**更新:** 2025-10-27  
**作者:** Claude Code