# 🎯 如何在 GitHub 上构建你的应用

## 📋 前提条件

✅ 已将配置推送到 GitHub
✅ 有 GitHub 账号访问权限

---

## 🚀 方法一：手动触发构建（推荐新手）

### 步骤 1: 访问 GitHub Actions 页面

1. 打开浏览器，访问你的仓库：
   ```
   https://github.com/你的用户名/LighthouseApp
   ```

2. 点击顶部导航栏的 **Actions** 标签
   ```
   Code  Issues  Pull requests  Actions  Projects  Wiki  Security  Insights
                                  ↑ 点这里
   ```

---

### 步骤 2: 选择 Workflow

在左侧栏看到可用的 workflows：

```
All workflows
├── Build Android APK              ← 仅构建 Android
├── Build Multi-Platform           ← 构建所有平台 ⭐推荐
└── Build Clash Core
```

**选择建议：**
- 🟢 **首次测试：** 选择 **Build Android APK**（快速）
- 🔵 **正式发布：** 选择 **Build Multi-Platform**（全平台）

---

### 步骤 3: 运行 Workflow

1. 点击选择的 workflow 名称

2. 右侧出现 **"Run workflow"** 下拉按钮
   ```
   [Run workflow ▼]
   ```

3. 点击下拉按钮，展开配置面板

---

### 步骤 4: 配置参数

#### 如果选择 "Build Android APK"：

```yaml
┌─────────────────────────────────────────┐
│ Run workflow                             │
├─────────────────────────────────────────┤
│ Use workflow from                        │
│ Branch: main                        [▼] │
│                                          │
│ 构建类型                                 │
│ ○ debug                                  │
│ ● release                                │
│                                          │
│ API 域名                                 │
│ [api.maodag.top________________]        │
│                                          │
│ OSS 配置地址 1                           │
│ [https://ppp2.oss-cn-hongkong...]       │
│                                          │
│ OSS 配置地址 2                           │
│ [https://xgp3.oss-ap-northeast-1...]    │
│                                          │
│ OSS 配置地址 3                           │
│ [https://xpp4.oss-ap-northeast-2...]    │
│                                          │
│ OSS 配置地址 4                           │
│ [https://xpp5.oss-ap-southeast-1...]    │
│                                          │
│         [Cancel]  [Run workflow]         │
└─────────────────────────────────────────┘
```

**配置说明：**
- **构建类型：** 选择 `release`（生产环境）
- **API 域名：** 填写你的后端域名（默认 `api.maodag.top`）
- **OSS 地址：** 保持默认或填写你的 CDN 地址

#### 如果选择 "Build Multi-Platform"：

额外多一个参数：
```yaml
│ 构建平台                                 │
│ [android,windows,macos,linux______]     │
```

**选项：**
- `android` - 仅 Android
- `windows` - 仅 Windows
- `macos` - 仅 macOS
- `linux` - 仅 Linux
- `android,windows` - Android + Windows
- `android,windows,macos,linux` - 全部平台 ⭐

---

### 步骤 5: 开始构建

1. 检查所有参数是否正确

2. 点击绿色的 **"Run workflow"** 按钮

3. 页面刷新，顶部出现黄色进度条：
   ```
   ⚠️ Build Android APK #1
   Queued - This workflow is in queue waiting to run
   ```

4. 几秒后变为蓝色（运行中）：
   ```
   🔵 Build Android APK #1
   In progress - This workflow is currently running
   ```

---

### 步骤 6: 监控构建进度

1. 点击运行记录（蓝色行）

2. 看到构建阶段：
   ```
   编译 libcore.aar          🔵 Running  (15分钟)
   编译 Android APK          ⏸️ Pending
   ```

3. 可以展开查看实时日志：
   ```
   ▼ 编译 libcore.aar
     ▼ 📦 编译 libcore.aar
       🚀 开始编译 libcore...
       [gomobile] installing...
       ✅ libcore.aar 生成成功
   ```

4. 等待所有阶段完成（约 30-85 分钟）

---

### 步骤 7: 下载构建产物

构建成功后：

1. 向下滚动到 **Artifacts** 区域
   ```
   📦 Artifacts
   
   Produced during runtime
   
   Name                          Size      Expires
   apk-arm64-v8a-release        42.5 MB   in 30 days   [Download]
   apk-armeabi-v7a-release      38.2 MB   in 30 days   [Download]
   apk-x86_64-release           45.1 MB   in 30 days   [Download]
   ```

2. 点击 **[Download]** 下载对应文件

3. 下载的是 ZIP 文件，解压后得到 APK：
   ```
   apk-arm64-v8a-release.zip
   └── BearVPN-android-arm64-v8a-release-20251027-abc1234.apk
   ```

---

## 🏷️ 方法二：推送标签自动构建

这种方式会自动构建并创建 GitHub Release。

### 步骤 1: 在本地打标签

```bash
cd /Users/mac/Project/Dart/LighthouseApp

# 创建标签（版本号必须以 v 开头）
git tag v1.0.0

# 查看标签
git tag
```

---

### 步骤 2: 推送标签到 GitHub

```bash
git push origin v1.0.0
```

**输出：**
```
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 160 bytes | 160.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0)
To github.com:你的用户名/LighthouseApp.git
 * [new tag]         v1.0.0 -> v1.0.0
```

---

### 步骤 3: 自动触发构建

1. 推送标签后，GitHub 自动检测到标签
2. 触发 **Build Multi-Platform** workflow
3. 使用默认配置构建所有平台

---

### 步骤 4: 查看构建进度

1. 访问 Actions 页面
2. 看到自动创建的构建任务：
   ```
   🔵 Build Multi-Platform
   v1.0.0
   ```

---

### 步骤 5: 下载 Release

构建成功后：

1. 访问 **Releases** 页面：
   ```
   https://github.com/你的用户名/LighthouseApp/releases
   ```

2. 看到新创建的 Release：
   ```
   📦 v1.0.0
   
   Latest  Pre-release
   
   🎉 BearVPN 多平台版本发布
   
   Assets (7)
   ├── BearVPN-android-arm64-v8a-release-*.apk        42.5 MB
   ├── BearVPN-android-armeabi-v7a-release-*.apk      38.2 MB
   ├── BearVPN-android-x86_64-release-*.apk           45.1 MB
   ├── BearVPN-windows-x64-release-*.zip              52.3 MB
   ├── BearVPN-macos-release-*.zip                    48.7 MB
   ├── BearVPN-linux-x64-release-*.tar.gz             45.9 MB
   └── Source code (zip)
   ```

3. 直接下载需要的文件

---

## ⏱️ 构建时间参考

| Workflow | 平台 | 时间 |
|---------|------|------|
| Build Android APK | Android | 30 分钟 |
| Build Multi-Platform | Android | 35 分钟 |
| Build Multi-Platform | Windows | 30 分钟 |
| Build Multi-Platform | macOS | 35 分钟 |
| Build Multi-Platform | Linux | 30 分钟 |
| Build Multi-Platform | 全部平台 | **60-85 分钟** |

**提示：** 平台是并行构建的，不是累加时间。

---

## 🎯 推荐流程

### 首次测试（验证流程）

```
1. 选择 "Build Android APK"
2. 使用默认配置
3. 运行构建
4. 等待 30 分钟
5. 下载 arm64-v8a APK
6. 安装测试
```

### 正式发布（生产环境）

```
1. 确保代码已测试
2. 本地打标签: git tag v1.0.0
3. 推送标签: git push origin v1.0.0
4. 等待 60-85 分钟
5. 在 Releases 页面下载所有平台
6. 分发给用户
```

---

## 🐛 常见问题

### Q1: 找不到 "Run workflow" 按钮

**原因：** 可能还在查看历史运行记录

**解决：**
1. 点击左侧的 workflow 名称
2. 确保在 workflow 主页面
3. 右侧会出现 "Run workflow" 按钮

---

### Q2: 构建失败

**排查步骤：**
1. 点击失败的运行记录
2. 展开红色的步骤
3. 查看错误日志
4. 常见错误：
   - libcore 编译失败 → 检查 Go 环境
   - APK 构建失败 → 检查 Flutter 依赖

---

### Q3: Artifacts 下载后是空的

**原因：** 构建可能失败

**解决：**
1. 检查构建日志
2. 确保所有步骤都是绿色 ✅
3. 重新运行构建

---

### Q4: 如何修改 API 域名

**方法 1：** 手动触发时修改参数

**方法 2：** 修改代码中的默认值
```dart
// lib/app/common/app_config.dart
static String kr_currentDomain = "api.example.com";
```

---

## 📞 需要帮助？

- **查看详细文档：** `.github/workflows/INDEX.md`
- **快速开始：** `.github/workflows/QUICKSTART.md`
- **问题反馈：** GitHub Issues

---

**准备好了吗？立即开始构建！** 🚀