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) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
5.8 KiB
5.8 KiB
📚 GitHub Actions 构建系统总览
🎯 快速导航
| 文档 | 用途 | 适合人群 |
|---|---|---|
| QUICKSTART.md | 3步快速开始 | 新手 |
| README.md | 基础说明 | 所有人 |
| BUILD_GUIDE.md | Android 详细指南 | Android 开发者 |
| MULTIPLATFORM_GUIDE.md | 多平台构建指南 | 全平台开发者 |
📋 可用的 Workflows
1. build-android-apk.yml - Android 专用构建
功能：
- ✅ 编译 libcore.aar
- ✅ 构建 Android APK (arm64/armv7/x86_64)
- ✅ 配置 API 域名和 OSS 地址
- ✅ Release 构建
触发条件：
- 推送到 main/develop 分支
- 创建 v* 标签
- 手动触发
文档： BUILD_GUIDE.md
2. build-multiplatform.yml - 多平台构建 ⭐推荐
功能：
- ✅ Android APK
- ✅ Windows 可执行文件
- ✅ macOS 应用
- ✅ Linux 可执行文件
- ✅ 可选择构建平台
- ✅ 统一配置管理
触发条件：
- 推送到 main/develop 分支
- 创建 v* 标签
- 手动触发
3. build-clash-core.yml - Clash 核心编译
功能：
- 编译 Clash Meta 核心
- 支持多架构 (arm64/armv7/x86_64)
触发条件：
- core/ 目录变更
- 手动触发
🚀 使用建议
场景 1: 日常开发（仅 Android）
使用： build-android-apk.yml
# 推送代码自动触发
git push origin main
时间： 约 30 分钟 产物： 3 个 Android APK
场景 2: 正式发布（所有平台）
使用： build-multiplatform.yml
# 1. 打标签
git tag v1.0.0
git push origin v1.0.0
# 2. 自动构建所有平台并创建 Release
时间： 约 60-85 分钟（并行） 产物： Android + Windows + macOS + Linux
场景 3: 测试特定平台
使用： build-multiplatform.yml 手动触发
构建平台: android,windows # 只构建这两个
时间： 约 35 分钟 产物： 指定平台
📦 构建产物对比
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
多平台构建
# 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
# Windows
BearVPN-windows-x64-release-20251027-abc1234.zip
# macOS
BearVPN-macos-release-20251027-abc1234.zip
# Linux
BearVPN-linux-x64-release-20251027-abc1234.tar.gz
⚙️ 配置参数说明
所有 Workflow 通用参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| 构建类型 | release |
debug 或 release |
| API 域名 | api.maodag.top |
后端服务器地址 |
| OSS 地址 1 | 香港 CDN | 配置文件源 |
| OSS 地址 2 | 东京 CDN | 备用配置源 |
| OSS 地址 3 | 首尔 CDN | 备用配置源 |
| OSS 地址 4 | 新加坡 CDN | 备用配置源 |
多平台专用参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| 构建平台 | android,windows,macos,linux |
选择构建的平台 |
⏱️ 构建时间对比
| Workflow | 单平台 | 全平台 |
|---|---|---|
| Android 专用 | 30分钟 | - |
| 多平台 | 30-40分钟 | 60-85分钟 |
🎯 选择 Workflow 的建议
选择 build-android-apk.yml 如果：
- ✅ 只需要 Android 版本
- ✅ 快速迭代开发
- ✅ CI/CD 自动触发
选择 build-multiplatform.yml 如果：
- ✅ 需要桌面版本
- ✅ 正式版本发布
- ✅ 需要灵活选择平台
🔧 环境配置
必需的 Secrets（用于 Release 签名）
Android:
KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD
macOS:
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
Windows:
WINDOWS_CERTIFICATE_BASE64
WINDOWS_CERTIFICATE_PASSWORD
说明： 如果不配置签名，可以使用 debug 构建。
📊 构建流程图
Android 专用
Checkout 代码
↓
编译 libcore.aar (15min)
↓
配置 API/OSS
↓
构建 APK (20min)
↓
上传产物
多平台
Checkout 代码
↓
编译 libcore.aar (15min)
↓
├─→ Android (20min) ─┐
├─→ Windows (15min) ─┤
├─→ macOS (20min) ─┼─→ 创建 Release
└─→ Linux (15min) ─┘
🐛 故障排查
问题 1: libcore 编译失败
检查：
- Go 环境是否正常
- gomobile 是否安装
- 网络连接（下载依赖）
日志位置： build-libcore job
问题 2: Android 构建失败
常见原因：
- libcore.aar 未生成
- Gradle 依赖问题
- 签名配置错误
解决： 查看 build-android job 日志
问题 3: macOS 构建失败
常见原因：
- 签名证书未配置
- Xcode 版本不兼容
解决：
- 使用 debug 构建
- 或配置签名证书
💡 高级用法
1. 定时构建
添加到 workflow:
on:
schedule:
- cron: '0 2 * * *' # 每天UTC 2:00
2. PR 自动构建
已配置：推送 PR 到 main 分支自动触发
3. 构建通知
可集成 Telegram/Slack/钉钉通知
📞 获取帮助
- 查看文档： 本目录下的 Markdown 文件
- 查看日志： GitHub Actions 页面
- 提交问题： Issues 页面
🔗 相关链接
版本： 1.0.0
更新： 2025-10-27
作者： Claude Code