Rust d02eed3bd8 docs: 添加 GitHub Actions 构建文档并锁定 libcore 版本

- 添加完整的 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)
  - 防止在线编译时使用最新版本
  - 确保构建稳定性和一致性

2025-10-27 23:11:21 +08:00

7.2 KiB

Raw Blame History

🌐 多平台构建完全指南

📋 支持的平台

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

🚀 快速开始

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

打开 GitHub Actions 页面
选择 Build Multi-Platform
点击 Run workflow
配置参数：

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

点击 Run workflow 开始

方法 2: 仅构建指定平台

场景： 只需要 Android 和 Windows 版本

构建平台: 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/                         # 资源文件

运行：

解压 ZIP 文件
双击 BearVPN.exe 运行
如提示缺少依赖，安装 VC++ Redistributable

macOS

BearVPN-macos-release-20251027-abc1234.zip

内容：

BearVPN.app                   # 应用程序包（Universal）

安装：

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

支持架构：

Intel (x86_64)
Apple Silicon (arm64)

Linux

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

内容结构：

bearvpn                       # 可执行文件
lib/                          # 共享库
data/                         # 资源文件

运行：

# 1. 解压
tar -xzf BearVPN-linux-x64-release-*.tar.gz
cd bundle

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

# 3. 运行
./bearvpn

依赖要求：

GTK+ 3
libstdc++12

安装依赖（Ubuntu/Debian）：

sudo apt-get install libgtk-3-0 libstdc++6

安装依赖（Fedora/RHEL）：

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 页面下载

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

从 Releases 下载（推送标签时）

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

🎯 使用场景

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

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

优点： 快速，约20分钟

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

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

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

场景 3: 仅桌面平台

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

用途： 桌面版更新

🐛 常见问题

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

原因： Windows runner 默认有 7z

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

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

原因： Release 构建需要签名

解决方案：

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

方法 2： 配置签名证书（生产用）

# 在 Secrets 中添加
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
MACOS_KEYCHAIN_PASSWORD
PROVISIONING_PROFILE_BASE64

Q3: Linux 运行时提示缺少库

错误：

error while loading shared libraries: libgtk-3.so.0

解决：

sudo apt-get update
sudo apt-get install libgtk-3-0

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

方法 1： 手动触发指定平台

构建平台: android  # 只构建 Android

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

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

优化方案：

仅构建需要的平台

构建平台: android  # 而不是全部

使用缓存（已配置）
- Flutter SDK 缓存
- Gradle 缓存
- Go modules 缓存
分批构建
- 白天构建 Android/Windows
- 晚上构建 macOS/Linux

💡 高级用法

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

修改 workflow:

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

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

技巧 2: 定时自动构建

添加到 workflow:

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

技巧 3: 构建完成通知

添加 Telegram 通知:

- 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:

# Secrets 配置
KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD

macOS:

# Secrets 配置
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD

Windows:

# Secrets 配置
WINDOWS_CERTIFICATE_BASE64
WINDOWS_CERTIFICATE_PASSWORD

📞 需要帮助？

查看 GitHub Actions 文档
查看 Flutter 桌面支持
提交 Issue

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

7.2 KiB Raw Blame History Unescape Escape