构建 - YumeBox

只运行 Gradle 不会生成缺失的 jniLibs；首次构建请先完成原生构建.

环境要求

工具	版本	用途
OpenJDK	24	Gradle 和 Android 编译
Android SDK	API 37	编译与目标平台
Android NDK	30.0.14904198	Go、Rust、C/C++ 原生构建
CMake	3.22.1	构建 C/C++ 组件
Python	3.10 或更高	执行构建脚本
Go	1.26	构建 mihomo 核心
Rust	nightly	构建配置编译器
cargo-ndk	最新版本	为 Android 编译 Rust
Git、patch	可用	同步内核与应用 Go 补丁

当前应用只构建 arm64-v8a，对应 Rust target 为 aarch64-linux-android.

准备仓库

获取源码

git clone https://github.com/YumeYucca/YumeBox.git
cd YumeBox

配置 Android SDK

安装 API 37、NDK 30.0.14904198 和 CMake 3.22.1，然后在仓库根目录创建 local.properties：

sdk.dir=C:/Android/Sdk

NDK 会根据 gradle.properties 中的 android.ndkVersion 自动定位.

准备 Go 与 Rust

rustup toolchain install nightly --component rust-src
rustup target add --toolchain nightly aarch64-linux-android
cargo install cargo-ndk

构建 Go 核心前，还需要将 .github/patch/ 中的补丁应用到 go env GOROOT.CI 会在构建原生组件前自动执行这一步.在 Git Bash 或 WSL 中执行：

project_root="$PWD"
go_root="$(go env GOROOT)"
for patch_file in "$project_root"/.github/patch/*.patch; do
  if (cd "$go_root" && patch --forward --dry-run -p 1 < "$patch_file") >/dev/null 2>&1; then
    (cd "$go_root" && patch --forward -p 1 < "$patch_file")
  elif (cd "$go_root" && patch --reverse --dry-run -p 1 < "$patch_file") >/dev/null 2>&1; then
    echo "已应用：$patch_file"
  else
    echo "无法应用：$patch_file" >&2
    exit 1
  fi
done

同步 mihomo

选择一个内核通道.默认使用 Alpha：

python scripts/sync_kernel.py alpha

也可以使用 Meta：

python scripts/sync_kernel.py meta

构建原生组件

完整构建

完整构建会生成所有原生库，并下载 Geo 数据：

python scripts/native-build.py --all

按组件构建

参数	输出或作用
`--go`	mihomo 共享核心、预览库和 PIE 启动壳
`--rust`	Rust 配置编译器 `liboverride.so`
`--compat`	核心进程通信桥 `libcompat.so`
`--loader`	APK payload loader `libloader.so`
`--shell`	仅构建 mihomo PIE 启动壳
`--geo`	下载并压缩 Geo 数据与 BundleMRS
`--clean`	清理原生、Geo 和版本标记

本机调试可只构建当前 ABI：

ABI_APP_LIST=arm64-v8a python scripts/native-build.py --go --rust --compat --loader

$env:ABI_APP_LIST = "arm64-v8a"
python scripts/native-build.py --go --rust --compat --loader

构建成功后，jniLibs/arm64-v8a/ 应包含：

文件	用途
`libmihomo.so`	mihomo PIE 启动壳
`libmihomocore.so`	mihomo Go 共享核心
`libpreview.so`	配置预览
`liboverride.so`	覆写编译
`libcompat.so`	核心通信桥
`libloader.so`	APK 原生载荷加载
`core-version.properties`	内核分支、提交和构建信息

Geo 数据位于 build/generated/assets/geo/：

geoip.metadb.xz
geosite.dat.xz
ASN.mmdb.xz
BundleMRS.7z

构建 APK

Debug

Debug 适合本地安装和调试：

./gradlew :app:assembleDebug
./gradlew -Pgeo.bundle=true :app:assembleDebug

.\gradlew.bat :app:assembleDebug
.\gradlew.bat -Pgeo.bundle=true :app:assembleDebug

Release

Release 会启用压缩和资源收缩：

./gradlew -Pgeo.bundle=false :app:assembleRelease
./gradlew -Pgeo.bundle=true :app:assembleRelease

.\gradlew.bat -Pgeo.bundle=false :app:assembleRelease
.\gradlew.bat -Pgeo.bundle=true :app:assembleRelease

Geo 数据变体

变体	内容	适用场景
`external`	不内置 Geo 数据	体积更小，首次启动需要下载
`builtin`	内置 Geo 数据	首次安装或离线使用

两种变体使用相同的应用代码和内核；差异只在 Geo 资源是否打包进 APK. APK 默认输出到：

app/build/outputs/apk/debug/
app/build/outputs/apk/release/

本地构建通常生成 YumeBox-external.apk 或 YumeBox-builtin.apk.实际文件名以输出目录为准.

Release 签名

本地验证可以不配置正式签名；发布 APK 需要仓库根目录中的 release.keystore 和 signing.properties：

keystore.password=你的仓库密码
key.alias=yumebox
key.password=你的密钥密码

字段	说明
`keystore.password`	keystore 密码
`key.alias`	签名密钥别名
`key.password`	签名密钥密码

不要提交 release.keystore 或 signing.properties.

CI 构建

阶段	主要工作	结果
原生构建	同步内核，构建 Go、Rust、C/C++ 和 loader	`native-*` 构建产物
APK 构建	下载原生产物，分别打包 `builtin` 和 `external`	两个 Release APK
发布准备	计算版本、生成 SHA-256 和元数据	发布目录与更新信息
Release 发布	上传 APK 和元数据	GitHub Release

CI 使用 arm64-v8a，并通过 build.number、build.hash 和 build.branch 写入构建版本信息.

验证安装

adb install -r app/build/outputs/apk/debug/YumeBox-external.apk

如果文件名不同，先查看 app/build/outputs/apk/ 中的实际产物.

常见问题

现象	处理
`jniLibs/arm64-v8a` 缺少 `.so`	先运行 `python scripts/native-build.py --all`.
找不到 Android SDK	检查 `local.properties` 或 `ANDROID_SDK_ROOT`.
找不到 NDK	安装 `30.0.14904198`，不要使用其他版本替代.
`cargo-ndk` 或 Rust target 缺失	重新安装 nightly、`rust-src` 和 `aarch64-linux-android`.
Go 补丁无法应用	检查补丁是否已经应用，或换用专用 Go SDK.
`builtin` 缺少 Geo 文件	先运行 `python scripts/native-build.py --geo`.
ABI 不受支持	当前项目只支持 `arm64-v8a`.

更多构建错误请查看常见问题.

开始

指南

覆写

更多

构建

环境要求

准备仓库

构建原生组件

完整构建

按组件构建

构建 APK

Debug

Release

Geo 数据变体

Release 签名

CI 构建

验证安装

常见问题

​环境要求

​准备仓库

​构建原生组件

​完整构建

​按组件构建

​构建 APK

​Debug

​Release

​Geo 数据变体

​Release 签名

​CI 构建

​验证安装

​常见问题

环境要求

准备仓库

构建原生组件

完整构建

按组件构建

构建 APK

Debug

Release

Geo 数据变体

Release 签名

CI 构建

验证安装

常见问题