Rust
d02eed3bd8
- 添加完整的 GitHub Actions 构建指南文档 - BUILD_GUIDE.md: Android 详细构建指南 - MULTIPLATFORM_GUIDE.md: 多平台构建指南 - HOW_TO_BUILD.md: 分步操作教程 - QUICKSTART.md: 3步快速开始指南 - INDEX.md: 文档总览索引 - README.md: 基础说明 - 创建 docs/ 目录存放项目文档 - 锁定 libcore 子模块到 f993a57 (v3.1.7) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
408 lines
7.2 KiB
Markdown
408 lines
7.2 KiB
Markdown
# 🌐 多平台构建完全指南
|
||
|
||
## 📋 支持的平台
|
||
|
||
✅ **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
|