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) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
319 lines
5.8 KiB
Markdown
319 lines
5.8 KiB
Markdown
# 📚 GitHub Actions 构建系统总览
|
||
|
||
## 🎯 快速导航
|
||
|
||
| 文档 | 用途 | 适合人群 |
|
||
|-----|------|---------|
|
||
| **[QUICKSTART.md](./QUICKSTART.md)** | 3步快速开始 | 新手 |
|
||
| **[README.md](./README.md)** | 基础说明 | 所有人 |
|
||
| **[BUILD_GUIDE.md](./BUILD_GUIDE.md)** | Android 详细指南 | Android 开发者 |
|
||
| **[MULTIPLATFORM_GUIDE.md](./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](./BUILD_GUIDE.md)
|
||
|
||
---
|
||
|
||
### 2. `build-multiplatform.yml` - 多平台构建 ⭐推荐
|
||
|
||
**功能：**
|
||
- ✅ Android APK
|
||
- ✅ Windows 可执行文件
|
||
- ✅ macOS 应用
|
||
- ✅ Linux 可执行文件
|
||
- ✅ 可选择构建平台
|
||
- ✅ 统一配置管理
|
||
|
||
**触发条件：**
|
||
- 推送到 main/develop 分支
|
||
- 创建 v* 标签
|
||
- 手动触发
|
||
|
||
**文档：** [MULTIPLATFORM_GUIDE.md](./MULTIPLATFORM_GUIDE.md)
|
||
|
||
---
|
||
|
||
### 3. `build-clash-core.yml` - Clash 核心编译
|
||
|
||
**功能：**
|
||
- 编译 Clash Meta 核心
|
||
- 支持多架构 (arm64/armv7/x86_64)
|
||
|
||
**触发条件：**
|
||
- core/ 目录变更
|
||
- 手动触发
|
||
|
||
---
|
||
|
||
## 🚀 使用建议
|
||
|
||
### 场景 1: 日常开发（仅 Android）
|
||
|
||
**使用：** `build-android-apk.yml`
|
||
```bash
|
||
# 推送代码自动触发
|
||
git push origin main
|
||
```
|
||
|
||
**时间：** 约 30 分钟
|
||
**产物：** 3 个 Android APK
|
||
|
||
---
|
||
|
||
### 场景 2: 正式发布（所有平台）
|
||
|
||
**使用：** `build-multiplatform.yml`
|
||
```bash
|
||
# 1. 打标签
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
|
||
# 2. 自动构建所有平台并创建 Release
|
||
```
|
||
|
||
**时间：** 约 60-85 分钟（并行）
|
||
**产物：** Android + Windows + macOS + Linux
|
||
|
||
---
|
||
|
||
### 场景 3: 测试特定平台
|
||
|
||
**使用：** `build-multiplatform.yml` 手动触发
|
||
```yaml
|
||
构建平台: 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 编译失败
|
||
|
||
**检查：**
|
||
1. Go 环境是否正常
|
||
2. gomobile 是否安装
|
||
3. 网络连接（下载依赖）
|
||
|
||
**日志位置：** `build-libcore` job
|
||
|
||
---
|
||
|
||
### 问题 2: Android 构建失败
|
||
|
||
**常见原因：**
|
||
- libcore.aar 未生成
|
||
- Gradle 依赖问题
|
||
- 签名配置错误
|
||
|
||
**解决：** 查看 `build-android` job 日志
|
||
|
||
---
|
||
|
||
### 问题 3: macOS 构建失败
|
||
|
||
**常见原因：**
|
||
- 签名证书未配置
|
||
- Xcode 版本不兼容
|
||
|
||
**解决：**
|
||
- 使用 debug 构建
|
||
- 或配置签名证书
|
||
|
||
---
|
||
|
||
## 💡 高级用法
|
||
|
||
### 1. 定时构建
|
||
|
||
添加到 workflow:
|
||
|
||
```yaml
|
||
on:
|
||
schedule:
|
||
- cron: '0 2 * * *' # 每天UTC 2:00
|
||
```
|
||
|
||
### 2. PR 自动构建
|
||
|
||
已配置：推送 PR 到 main 分支自动触发
|
||
|
||
### 3. 构建通知
|
||
|
||
可集成 Telegram/Slack/钉钉通知
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
- **查看文档：** 本目录下的 Markdown 文件
|
||
- **查看日志：** GitHub Actions 页面
|
||
- **提交问题：** Issues 页面
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [GitHub Actions 文档](https://docs.github.com/actions)
|
||
- [Flutter CI/CD](https://docs.flutter.dev/deployment/cd)
|
||
- [sing-box 文档](https://sing-box.sagernet.org/)
|
||
|
||
---
|
||
|
||
**版本：** 1.0.0
|
||
**更新：** 2025-10-27
|
||
**作者：** Claude Code
|