# 📚 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