构建

正式 APK 必须通过 packaging 入口构建；首次构建前请先完成原生组件准备。

​

环境要求

工具	版本	用途
OpenJDK	25	运行构建工具链
Android SDK	API 37、build-tools 37.0.0	编译、打包与签名
Android NDK	30.0.16248370	构建原生组件
CMake、Ninja	SDK CMake 3.22.1 或 PATH 中的版本	构建 C/C++ 组件
Python	3.10 或更高	执行构建脚本
Go	1.27（MetaCubeX/go）	构建 mihomo 核心
Rust	nightly、rust-src	构建配置编译器
cargo-ndk	最新	为 Android 编译 Rust

构建入口是仓库根目录的 kotlin 脚本（Windows 为 kotlin.bat），首次运行会自动下载所需的 Kotlin Toolchain，无需手动安装 Kotlin 或 Gradle。最低支持 Android 8.0（API 26），当前仅支持 arm64-v8a；NDK 版本、最低 SDK 与 ABI 均读取自 kernel.properties。

​

准备仓库

1. 获取源码

   git clone --recurse-submodules https://github.com/YumeYucca/YumeBox.git
   cd YumeBox
   
2. 配置 Android SDK

   安装 API 37、build-tools 37.0.0、NDK 30.0.16248370、CMake 3.22.1 与 Ninja，并接受 SDK 许可证。设置 ANDROID_HOME 指向 SDK，或在仓库根目录创建 local.properties：

   sdk.dir=C:/Android/Sdk
   

   ANDROID_HOME、ANDROID_SDK_ROOT 与 sdk.dir 需要指向同一个 SDK。

3. 准备 Go 与 Rust

   安装 MetaCubeX 维护的 Go 1.27（CI 使用同一版本）与 Rust nightly 工具链。建议使用专用 Go SDK，因为下一步会修改其 GOROOT：

   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 会在构建原生组件前自动执行；以下命令适用于 Linux、macOS 与 Git Bash：

   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
   
4. 同步 mihomo 内核

   默认同步 Alpha 分支，也可以改用 Meta：

   python scripts/sync_kernel.py alpha
   python scripts/sync_kernel.py meta
   

​

构建原生组件

​

完整构建

python scripts/native-build.py --all

该命令会生成全部原生库并下载 Geo 数据。

​

按组件构建

参数	作用
--go	mihomo 共享核心、预览库与 PIE 启动壳
--rust	配置编译器 liboverride.so
--compat	核心进程通信桥 libcompat.so
--loader	APK 载荷加载 libloader.so
--shell	仅构建 mihomo 与预览功能的 PIE 启动壳
--geo	下载并压缩 Geo 数据
--clean	清理构建产物

默认 ABI 取自 kernel.properties 的 abi.app.list，也可以用环境变量显式指定：

Linux Git Bash

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

​

构建 APK

构建命令为 kotlin run -m packaging，所有 -Pkey=value 参数放在 -- 之后传给打包入口；PowerShell 中含点的参数需要用单引号包裹。

​

Debug

Debug 适合本地安装和调试，默认不内置 Geo：

Linux / macOS

sh kotlin run -m packaging -- --build-type=debug
sh kotlin run -m packaging -- --build-type=debug -Pgeo.bundle=true

​

Release

Release 会构建 loader DEX 并封装 payload，需要先完成下文的签名配置：

Linux / macOS

sh kotlin run -m packaging -- --build-type=release -Pgeo.bundle=false
sh kotlin run -m packaging -- --build-type=release -Pgeo.bundle=true

验证通过的 APK 输出到 output_apk/debug/ 与 output_apk/release/，文件名为 YumeBox-external.apk 或 YumeBox-builtin.apk，并生成同名的 .apk.json，记录版本、SHA-256 等构建信息。

变体	参数	说明
external	-Pgeo.bundle=false	不内置 Geo，体积更小，首次启动需要下载
builtin	-Pgeo.bundle=true	内置 Geo，适合离线使用；构建前需先执行 python scripts/native-build.py --geo

​

签名配置

未配置签名时，Debug 自动生成并使用 debug keystore；只要仓库根目录存在 signing.properties，Debug 和 Release 都会优先使用它。Release 必须签名：在仓库根目录放置 release.keystore，并创建 signing.properties：

keystore.path=release.keystore
keystore.password=<keystore-password>
key.alias=yumebox
key.password=<key-password>

字段	说明
keystore.path	keystore 路径，相对仓库根目录或绝对路径
keystore.password	keystore 密码
key.alias	签名密钥别名
key.password	密钥密码

不要提交 release.keystore 和 signing.properties。

只有显式传入 --allow-unsigned 且没有 signing.properties 时才会生成未签名 APK；未签名 APK 无法通过 adb install 安装，CI 不使用此选项。

​

CI 构建

所有 CI 作业使用 macos-26，只构建 arm64-v8a：

阶段	主要工作	结果
并行准备	Toolchain 预编译、原生构建与 Geo 下载并行执行	编译缓存与原生产物
并行 APK 打包	打包、签名和验证 builtin / external	两个 Release APK
发布准备	计算版本号、生成 SHA-256 与更新元数据	发布目录与更新信息
Release 发布	上传 APK 与发布元数据	GitHub Release

CI 使用提交计数作为构建版本号，并写入提交哈希与分支信息。

​

验证安装

adb install -r output_apk/debug/YumeBox-external.apk

如果文件名不同，请先查看 output_apk/debug/ 中的实际产物。

​

常见问题

现象	处理
jniLibs/arm64-v8a 缺少 .so	先运行 python scripts/native-build.py --all。
找不到 SDK 或打包 SDK 不一致	检查 ANDROID_HOME、ANDROID_SDK_ROOT 与 local.properties，安装 API 37 / build-tools 37.0.0 并接受许可证。
NDK 缺失或版本不匹配	安装 kernel.properties 指定的 30.0.16248370。
CMake 或 Ninja 缺失	安装 SDK CMake 3.22.1，或在 PATH 中提供。
cargo-ndk 或 Rust target 缺失	安装 nightly、rust-src、aarch64-linux-android 和 cargo-ndk。
Go 补丁无法应用	确认使用 MetaCubeX/go 1.27，检查补丁是否已应用，必要时使用专用 Go SDK。
builtin 缺少 Geo 文件	先运行 python scripts/native-build.py --geo，确认三个 XZ 文件齐全。
Release 签名失败或无法安装	检查 signing.properties 的四个键与 keystore；覆盖安装须使用相同证书。
编译成功但没有最终 APK	移除 --compile-only，使用 packaging 入口并检查验证错误。
ABI 不受支持	当前仅支持 arm64-v8a。

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