> ## Documentation Index
> Fetch the complete documentation index at: https://yumebox.yumeyuka.moe/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建

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

<Frame>
  <img src="https://mintcdn.com/yumebox/37Z_Xsb-cHWca0U0/images/diagrams/yumebox-build-pipeline.svg?fit=max&auto=format&n=37Z_Xsb-cHWca0U0&q=85&s=8a2f6f0bc23529600e99481d11c36880" alt="YumeBox 本地与 CI 构建链路" noZoom={true} width="937" height="895" data-path="images/diagrams/yumebox-build-pipeline.svg" />
</Frame>

## 环境要求

| 工具          | 版本            | 用途                  |
| ----------- | ------------- | ------------------- |
| 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`.

## 准备仓库

<Steps>
  <Step title="获取源码">
    ```bash theme={null}
    git clone https://github.com/YumeYucca/YumeBox.git
    cd YumeBox
    ```
  </Step>

  <Step title="配置 Android SDK">
    安装 API 37、NDK 30.0.14904198 和 CMake 3.22.1，然后在仓库根目录创建 `local.properties`：

    ```properties theme={null}
    sdk.dir=C:/Android/Sdk
    ```

    NDK 会根据 `gradle.properties` 中的 `android.ndkVersion` 自动定位.
  </Step>

  <Step title="准备 Go 与 Rust">
    ```bash theme={null}
    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 中执行：

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="同步 mihomo">
    选择一个内核通道.默认使用 Alpha：

    ```bash theme={null}
    python scripts/sync_kernel.py alpha
    ```

    也可以使用 Meta：

    ```bash theme={null}
    python scripts/sync_kernel.py meta
    ```
  </Step>
</Steps>

## 构建原生组件

### 完整构建

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

```bash theme={null}
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：

<CodeGroup>
  ```bash Linux / macOS / Git Bash theme={null}
  ABI_APP_LIST=arm64-v8a python scripts/native-build.py --go --rust --compat --loader
  ```

  ```powershell Windows PowerShell theme={null}
  $env:ABI_APP_LIST = "arm64-v8a"
  python scripts/native-build.py --go --rust --compat --loader
  ```
</CodeGroup>

构建成功后，`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/`：

```text theme={null}
geoip.metadb.xz
geosite.dat.xz
ASN.mmdb.xz
BundleMRS.7z
```

## 构建 APK

### Debug

Debug 适合本地安装和调试：

<CodeGroup>
  ```bash Linux / macOS theme={null}
  ./gradlew :app:assembleDebug
  ./gradlew -Pgeo.bundle=true :app:assembleDebug
  ```

  ```powershell Windows theme={null}
  .\gradlew.bat :app:assembleDebug
  .\gradlew.bat -Pgeo.bundle=true :app:assembleDebug
  ```
</CodeGroup>

### Release

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

<CodeGroup>
  ```bash Linux / macOS theme={null}
  ./gradlew -Pgeo.bundle=false :app:assembleRelease
  ./gradlew -Pgeo.bundle=true :app:assembleRelease
  ```

  ```powershell Windows theme={null}
  .\gradlew.bat -Pgeo.bundle=false :app:assembleRelease
  .\gradlew.bat -Pgeo.bundle=true :app:assembleRelease
  ```
</CodeGroup>

### Geo 数据变体

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

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

APK 默认输出到：

```text theme={null}
app/build/outputs/apk/debug/
app/build/outputs/apk/release/
```

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

## Release 签名

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

```properties theme={null}
keystore.password=你的仓库密码
key.alias=yumebox
key.password=你的密钥密码
```

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

<Info>不要提交 `release.keystore` 或 `signing.properties`.</Info>

## 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` 写入构建版本信息.

## 验证安装

```bash theme={null}
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`.                               |

更多构建错误请查看[常见问题](/guide/faq).