hi-client/.github/workflows/BUILD_GUIDE.md

📖 GitHub Actions 构建完全指南

🎯 功能概述

本 workflow 支持：

✅ 自动编译 libcore.aar - sing-box 核心库 ✅ Release 构建 - 默认生成正式版 APK ✅ 可配置 API 域名 - 支持自定义后端域名 ✅ 可配置 OSS 地址 - 支持自定义配置文件 CDN ✅ 分架构打包 - 生成 arm64-v8a / armeabi-v7a / x86_64 版本 ✅ 自动创建 Release - 推送标签自动发布

---

🚀 使用方法

方法一：手动触发（推荐，支持自定义配置）

1. 打开 Actions 页面

   • 进入 GitHub 仓库
   • 点击顶部 Actions 标签

2. 选择 Workflow

   • 左侧选择 Build Android APK
   • 右侧点击 Run workflow 下拉框

3. 配置参数

   参数	说明	默认值
   构建类型	debug 或 release	release
   API 域名	后端 API 服务器域名	api.maodag.top
   OSS 地址 1	配置文件 CDN 地址（香港）	https://ppp2.oss-cn-hongkong.aliyuncs.com/bear1.txt
   OSS 地址 2	配置文件 CDN 地址（东京）	https://xgp3.oss-ap-northeast-1.aliyuncs.com/bear1.txt
   OSS 地址 3	配置文件 CDN 地址（首尔）	https://xpp4.oss-ap-northeast-2.aliyuncs.com/bear1.txt
   OSS 地址 4	配置文件 CDN 地址（新加坡）	https://xpp5.oss-ap-southeast-1.aliyuncs.com/bear1.txt

4. 开始构建

   • 点击绿色 Run workflow 按钮
   • 等待约 30 分钟完成

5. 下载 APK

   • 构建完成后，在运行记录页面找到 Artifacts 区域
   • 下载对应架构的 APK

---

方法二：推送代码自动构建（使用默认配置）

# 提交代码
git add .
git commit -m "feat: 新功能"

# 推送到 main 分支
git push origin main

注意： 自动触发的构建使用默认配置（api.maodag.top 和默认 OSS 地址）

---

方法三：创建 Release 版本

# 1. 打标签（必须以 v 开头）
git tag v1.0.0

# 2. 推送标签
git push origin v1.0.0

# 3. 自动触发构建并创建 Release
# 访问 https://github.com/你的用户名/LighthouseApp/releases 查看

---

📦 构建产物

APK 命名规则

BearVPN-{架构}-{类型}-{日期}-{提交哈希}.apk

示例：

BearVPN-arm64-v8a-release-20251027-abc1234.apk
BearVPN-armeabi-v7a-release-20251027-abc1234.apk
BearVPN-x86_64-release-20251027-abc1234.apk

架构说明

架构	适用设备	推荐度
arm64-v8a	2017年后的现代手机	⭐⭐⭐⭐⭐
armeabi-v7a	2012-2017年的老旧手机	⭐⭐
x86_64	Android 模拟器	⭐⭐⭐

大多数用户应下载 arm64-v8a 版本

---

🔧 配置示例

示例 1：修改 API 域名

如果你的后端部署在 api.example.com：

1. 手动触发 workflow
2. 将 API 域名 改为 api.example.com
3. OSS 地址保持默认
4. 点击 Run workflow

示例 2：使用自己的 CDN

如果你有自己的配置文件 CDN：

1. 手动触发 workflow
2. API 域名保持默认
3. 修改 OSS 地址 1-4 为你的 CDN 地址，例如：
   • OSS 地址 1: https://cdn1.example.com/config.txt
   • OSS 地址 2: https://cdn2.example.com/config.txt
   • OSS 地址 3: https://cdn3.example.com/config.txt
   • OSS 地址 4: https://cdn4.example.com/config.txt
4. 点击 Run workflow

示例 3：完全自定义配置

构建类型: release
API 域名: api.mycompany.com
OSS 地址 1: https://config.mycdn.com/v1/nodes.txt
OSS 地址 2: https://backup1.mycdn.com/v1/nodes.txt
OSS 地址 3: https://backup2.mycdn.com/v1/nodes.txt
OSS 地址 4: https://backup3.mycdn.com/v1/nodes.txt

---

⏱️ 构建时间

阶段	时间
编译 libcore.aar	10-15 分钟
编译 Flutter APK	15-20 分钟
总计	约 30 分钟

---

🔍 查看构建日志

1. 打开 Actions 页面
2. 点击对应的运行记录
3. 点击具体的 job（如 "编译 Android APK"）
4. 展开步骤查看详细日志

关键步骤：

• ⚙️ 配置 API 域名和 OSS 地址 - 查看配置是否正确替换
• 🔨 构建 APK - 查看编译过程
• 📦 重命名 APK 文件 - 查看生成的文件名和 MD5

---

🐛 常见问题

Q1: 如何验证配置是否生效？

A: 查看 ⚙️ 配置 API 域名和 OSS 地址 步骤的日志：

🔧 配置构建参数：
  API 域名: api.example.com
  OSS 地址 1: https://cdn1.example.com/config.txt
  ...

✅ 配置替换完成

📄 查看修改后的配置：
  static List<String> kr_baseDomains = ["api.example.com","api.example.com"];
  static String kr_currentDomain = "api.example.com";

如果看到你设置的域名，说明配置成功。

---

Q2: Release 构建和 Debug 构建有什么区别？

特性	Debug	Release
文件大小	较大	较小（优化后）
性能	较慢	快
调试信息	包含	移除
代码混淆	无	有
适用场景	开发测试	正式发布

推荐： 生产环境使用 release 构建

---

Q3: 如何使用环境变量配置（不想每次手动输入）？

在仓库 Settings → Secrets and variables → Actions → Variables 添加：

变量名	值
DEFAULT_API_DOMAIN	api.example.com
DEFAULT_OSS_URL_1	https://cdn1.example.com/config.txt
DEFAULT_OSS_URL_2	https://cdn2.example.com/config.txt
DEFAULT_OSS_URL_3	https://cdn3.example.com/config.txt
DEFAULT_OSS_URL_4	https://cdn4.example.com/config.txt

然后修改 workflow 文件，将默认值改为：

default: ${{ vars.DEFAULT_API_DOMAIN || 'api.maodag.top' }}

---

Q4: 构建失败 - "libcore.aar not found"

原因： libcore 编译失败

解决：

1. 检查 build-libcore job 的日志
2. 确认 Go 环境和 gomobile 安装成功
3. 确认 libcore 子模块已正确初始化

---

Q5: 如何配置签名（Release 构建必需）？

详见主文档 .github/workflows/README.md 的签名配置章节。

---

💡 高级技巧

技巧 1：同时构建多个版本

修改 build-apk job：

strategy:
  matrix:
    build_type: [debug, release]
    api_domain: ['api.maodag.top', 'api.example.com']

这样会生成 4 个 APK（2种类型 × 2个域名）

---

技巧 2：添加构建完成通知

在 workflow 最后添加：

- name: 📢 发送 Telegram 通知
  if: success()
  run: |
    curl -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage" \
      -d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
      -d text="✅ BearVPN 构建成功！下载: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"

需要先配置 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID Secrets。

---

技巧 3：缓存加速构建

workflow 已配置 Go 和 Flutter 缓存，首次构建约 30 分钟，后续构建可缩短至 15-20 分钟。

---

📊 构建状态徽章

在 README.md 中添加：

![Build Status](https://github.com/你的用户名/LighthouseApp/actions/workflows/build-android-apk.yml/badge.svg)

效果：

---

🔗 相关文件

• 主 Workflow: .github/workflows/build-android-apk.yml
• 配置文件: lib/app/common/app_config.dart
• libcore 源码: libcore/ 子模块

---

📞 需要帮助？

• 查看 GitHub Actions 文档
• 查看构建日志排查问题
• 提交 Issue 到仓库

---

生成时间: 2025-10-27 作者: Claude Code 版本: 1.0.0