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) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
367 lines
8.5 KiB
Markdown
367 lines
8.5 KiB
Markdown
# 🎯 如何在 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
|
||
|
||
---
|
||
|
||
**准备好了吗？立即开始构建！** 🚀
|