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

8.5 KiB

Raw Blame History

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

📋 前提条件

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

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

步骤 1: 访问 GitHub Actions 页面

打开浏览器，访问你的仓库：

https://github.com/你的用户名/LighthouseApp

点击顶部导航栏的 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

点击选择的 workflow 名称
右侧出现 "Run workflow" 下拉按钮
```
[Run workflow ▼]
```
点击下拉按钮，展开配置面板

步骤 4: 配置参数

如果选择 "Build Android APK"：

┌─────────────────────────────────────────┐
│ 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"：

额外多一个参数：

│ 构建平台                                 │
│ [android,windows,macos,linux______]     │

选项：

android - 仅 Android
windows - 仅 Windows
macos - 仅 macOS
linux - 仅 Linux
android,windows - Android + Windows
android,windows,macos,linux - 全部平台 ⭐

步骤 5: 开始构建

检查所有参数是否正确
点击绿色的 "Run workflow" 按钮

页面刷新，顶部出现黄色进度条：

⚠️ Build Android APK #1
Queued - This workflow is in queue waiting to run

几秒后变为蓝色（运行中）：

🔵 Build Android APK #1
In progress - This workflow is currently running

步骤 6: 监控构建进度

点击运行记录（蓝色行）

看到构建阶段：

编译 libcore.aar          🔵 Running  (15分钟)
编译 Android APK          ⏸️ Pending

可以展开查看实时日志：

▼ 编译 libcore.aar
  ▼ 📦 编译 libcore.aar
    🚀 开始编译 libcore...
    [gomobile] installing...
    ✅ libcore.aar 生成成功

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

步骤 7: 下载构建产物

构建成功后：

向下滚动到 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]

点击 [Download] 下载对应文件

下载的是 ZIP 文件，解压后得到 APK：

apk-arm64-v8a-release.zip
└── BearVPN-android-arm64-v8a-release-20251027-abc1234.apk

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

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

步骤 1: 在本地打标签

cd /Users/mac/Project/Dart/LighthouseApp

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

# 查看标签
git tag

步骤 2: 推送标签到 GitHub

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: 自动触发构建

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

步骤 4: 查看构建进度

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

步骤 5: 下载 Release

构建成功后：

访问 Releases 页面：

https://github.com/你的用户名/LighthouseApp/releases

看到新创建的 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)

直接下载需要的文件

⏱️ 构建时间参考

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" 按钮

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

解决：

点击左侧的 workflow 名称
确保在 workflow 主页面
右侧会出现 "Run workflow" 按钮

Q2: 构建失败

排查步骤：

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

Q3: Artifacts 下载后是空的

原因： 构建可能失败