Magisk 构建指南环境搭建、build.py 构建体系与 Native/Rust 开发工作流【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk本篇技术指南基于 Magisk 官方文档 docs/build.md 展开系统讲解如何从零搭建 Magisk 的开发与构建环境包括平台与工具链要求、build.py全部子命令、config.prop构建配置项以及 NativeC/C/Rust与 Android 应用两条构建线的源码级实现原理。读完后你将能够独立完成 Magisk 全量构建、自定义签名分发构建并为 Rust 代码接入 rustup/rust-analyzer 等开发工具。一、构建体系概览Magisk 仓库是一个多语言工程native/目录包含 C、C 与 Rust 编写的原生二进制magisk、magiskinit、magiskboot、magiskpolicy、resetpropapp/目录是一个多模块 Gradle 工程Compose 新版 UI、legacy 旧版 UI、stub 应用、core 核心模块等。整个仓库由 build.py 统一编排scripts/env.py 负责工具链探测与环境注入。构建体系的关键事实均来自源码构建编排入口为 build.py其parse_args()build.py#L704-L808定义了全部子命令环境探测与工具链封装在 scripts/env.py包括 NDK 路径解析、JDK 检查、cargo 环境注入文档 docs/build.md 中的每一条命令都能在build.py中找到对应的子命令实现。二、环境搭建Setup Environment2.1 支持的平台文档明确列出的受支持平台为Linux x64macOS x64IntelmacOS arm64Apple SiliconWindows x64需额外开启developer mode因为构建过程依赖符号链接支持2.2 基础工具链工具要求说明Python3.8build.py的解释器scripts/env.py#L158-L159 会在版本不足时直接报错Requires Python 3.8colorama可选仅 Windowspip install coloramaWindows 终端输出 ANSI 彩色标题缺失时 scripts/env.py#L147-L155 会自动降级为无色输出Git最新版Windows 安装时需勾选Enable symbolic linksAndroid Studio最新版用于初始化和提供 SDK/JDKJDK见下节构建 Android 应用需要Unix 下用系统包管理器安装 python3 与 git 即可Windows 下从官方渠道安装并务必在 Python 安装时勾选 Add Python to PATH。2.3 环境变量文档要求设置两个关键环境变量它们在 scripts/env.py 的Paths类scripts/env.py#L33-L50中被消费# 必须指向 Android SDK 根目录Android Studio 设置中可查 export ANDROID_HOME/path/to/android-sdk # 推荐指向 Android Studio 安装路径构建脚本会自动找到其捆绑的 JBRJDK export ANDROID_STUDIO/path/to/Android\ StudioPaths类在ANDROID_HOME缺失时会尝试回退到ANDROID_SDK_ROOT两者都没有则报错退出。JDK 方面ensure_jdk()scripts/env.py#L107-L135的当前实现是若设置了ANDROID_STUDIO则优先把jbr/Linux或Contents/jbr/Contents/HomemacOS下的 JBR 前置到PATH否则要求系统javac可用且版本为 21错误提示原文为install JDK 21 and make sure javac is available in PATH。因此实际以仓库代码为准需要 JBR 或 JDK 21。2.4 克隆源码与安装 NDKgit clone --recurse-submodules https://gitcode.com/GitHub_Trending/ma/Magisk.git cd Magisk # 让脚本自动下载并安装 Magisk 专用 NDKONDK ./build.py ndk./build.py ndk对应setup_ndk()build.py#L507-L522它按 scripts/env.py#L13 中固定的ondk_version r30.1下载 ONDK 发行包r30.1 是 Magisk 定制扩展版 NDK解压到$ANDROID_HOME/ndk/后重命名为$ANDROID_HOME/ndk/magisk。注意ensure_toolchain()scripts/env.py#L68-L83每次构建都会校验ndk/magisk/ONDK_VERSION与期望值一致版本不匹配时会提示重新执行build.py ndk——即构建强绑定 ONDK r30.1不能用任意官方 NDK 替代因为 ONDK 捆绑了 Magisk 所需的完整 Rust 交叉工具链。三、构建build.py 子命令全景3.1 基本用法文档给出的两条核心命令./build.py all # 构建全部组件并产出最终 Magisk APK ./build.py # 不带参数时打印全部可用 action 的帮助每个 action 都支持-h查看专属帮助如./build.py binary -h注意当前binary动作名已演进实际子命令见下表。此外所有 action 均支持全局参数build.py#L707-L718参数含义-r/--release以 release 模式编译native 传MAGISK_DEBUG1/release profileapp 构建assembleRelease-v/--verbose可重复使用-v打印执行命令-vv进一步透传V1/--verbose-c/--config指定配置文件默认config.prop3.2 子命令完整参考以下子命令来自parse_args()build.py#L719-L802实际注册表子命令说明实现函数all构建一切native app testbuild_all()native [targets...]构建原生二进制可指定目标子集build_native()app构建新版 Magisk 应用build_app()app-legacy构建 legacy 版应用build_app_legacy()stub构建 stub 应用build_stub()test构建 test 应用强制 release 以避免类名冲突build_test()clean [targets...]清理构建产物目标为native/cpp/rust/appcleanup()ndk下载并安装 Magisk NDKONDKsetup_ndk()emulator [apk]初始化开发用 AVD 并注入构建产物setup_avd()avd_patch image output修补 AVD 的 ramdisk.img / init_boot.imgpatch_avd_file()cargo cmd...在native/src下代理执行任意 cargo 命令cargo_cli()clippy对 Rust 源码跑 clippy 检查支持--abi/-r/-dclippy_cli()rustup wrapper_dir生成 rustup wrapper 目录JetBrains IDE 方案见第四节setup_rustup()gen [--abi abi]生成 IDE 所需的 FFI 绑定与compile_commands.jsongen_ide()native动作可接受的目标为support_targets {magisk, magiskinit, magiskboot, magiskpolicy, resetprop}build.py#L34不传参时默认构建除resetprop外的四个目标。3.3all的执行流程build_all()build.py#L418-L421依次执行三步build_native()构建全部默认原生目标build_app()执行app/gradlew :apk:assembleDebug|Release把产物改名为app-type.apk放入输出目录并从app/core/src/type/assets/stub.apk复制出stub-type.apkbuild_test()以 release 模式构建:test模块并输出test.apk。所有构建产物默认输出到仓库根目录的out/可由config.prop的outdir改写。四、构建配置config.prop 与 gradle.properties文档指出通过config.prop配置构建仓库提供样本config.prop.sample。样本 config.prop.sample 的全部变量均为可选留空即保持默认值# The version name of Magisk. Default: git HEAD short SHA1 versionstring # Output path. Default: out outdirstring # List of ABIs to build, separated with , # Default: armeabi-v7a,x86,arm64-v8a,x86_64 abiList[string] ##################################################### # Signing configs for signing zips and APKs # These 4 variables has to be either all set or not ##################################################### # Path to keystore file keyStorestring # Keystore password keyStorePassstring # The desired key alias in the keystore keyAliasstring # Password of specified key alias keyPassstring结合 build.py 的配置加载实现load_config()build.py#L671-L701与parse_props()build.py#L644-L658可以确认几个文档未明说的细节版本号默认值version缺省为git rev-parse --short8 HEAD的短 SHA1versionCode缺省1000000gradle.properties 覆盖load_config()还会解析 app/gradle.properties 中以magisk.开头的键并去掉前缀合并进配置。当前仓库实际生效的是magisk.stubVersion40与magisk.versionCode30700也就是说versionCode的真实默认值来自该文件而非 1000000ABI 别名set_build_abis()build.py#L661-L668支持别名arm/arm32→armeabi-v7a、arm64→arm64-v8a、x64→x86_64除默认四个 ABI 外support_abis还包含非默认的riscv64build.py#L20-L26拼写错误会直接报Unknown ABI解析规则配置文件按行解析keyvalue#开头为注释空 key 或 value 的行被忽略签名四元组keyStore/keyStorePass/keyAlias/keyPass必须全部设置或全部不设置Gradle 侧消费逻辑见第五节。五、Native 构建管线原理build_native()build.py#L272-L287是一条Rust 静态库 C/C 链接的两段式管线5.1 版本宏生成dump_flags_native()build.py#L257-L269把version/versionCode/debug 标志分别写入native/out/generated/flags.hC/C 侧与flags.rsRust 侧。App 侧对应dump_flags_app()生成app/build/flags.prop。这也是文档先执行./build.py binary现对应native/gen再打开 IDE的原因——部分代码是构建期生成物。5.2 Rust 段build_rust_src()build.py#L199-L243ensure_cargo()scripts/env.py#L86-L104注入环境变量优先走 rustup 代理并把RUSTUP_TOOLCHAIN指到 ONDK 自带的$ANDROID_HOME/ndk/magisk/toolchains/rust无 rustup 时则直接把该工具链bin前置到PATH并在 Unix 上补LD_LIBRARY_PATH/DYLD_FALLBACK_LIBRARY_PATH供 cargo 调用的目标机工具链二进制定位运行时库在native/src下逐目标执行cargo build -p target [-r] --target triple覆盖每个 ABI 的 triple如aarch64-linux-android、thumbv7neon-linux-androideabi、i686-linux-android、x86_64-linux-android把native/out/rust/triple/profile/libtarget.a搬移到native/out/abi/libtarget-rs.a供后续 C 链接。注意一个细节若 targets 包含resetprop会自动追加magiskbuild.py#L202-L205因为 resetprop 与 magisk 主体共享 Rust 编译单元。Rust workspace 定义在 native/src/Cargo.toml成员为base、boot、core、init、sepolicy等其 profile 配置采用opt-levelz体积优先 LTO panicimmediate-abort与 Magisk 运行在受限环境init 阶段、无完整 libc 运行时等的定位一致。5.3 C/C 段build_cpp_src()build.py#L160-L197通过ndk-build分批编译第一批按目标传入B_MAGISK1/B_POLICY1/B_PRELOAD1/B_PROP1编译主程序与策略工具第二批按B_INIT1/B_BOOT1并固定追加B_CRT01编译 init 与 boot 修补程序需要静态 C 运行时非 release 模式自动追加MAGISK_DEBUG1并行度取-jcpu_count编译完成后collect_ndk_build()把native/libs/abi/下的产物移动到native/out/abi/若构建了magisk或magiskpolicy最后执行clean_elf()build.py#L121-L132调用 tools/elf-cleaner 这两个 ELF 二进制剥离符号等敏感信息。5.4 缓存加速ensure_toolchain()scripts/env.py#L68-L83会检测系统 PATH 中的sccache/ccache找到后分别注入RUSTC_WRAPPERRust 段缓存、NDK_CCACHEC/C 段缓存sccache 同时会关闭CARGO_INCREMENTAL。这解释了文档中可选安装之外的又一好处——重复构建提速。六、IDE 支持文档IDE Support一节指出Kotlin/Java/C/C 代码在 Android Studio 中开箱即用仓库可以直接作为项目打开但动任何 native 代码之前先执行./build.py binary当前版本对应./build.py native或./build.py gen因为部分生成代码只在构建过程中创建。这一点由gen_ide()build.py#L429-L469精确覆盖它做三件事cargo check --target abi触发 build.rs生成 Rust/C FFI 绑定cxx 相关生成物以全目标标志跑一次ndk-build compile_commands.json产出native/compile_commands.json供 clangd 使用会主动剔除NDK_CCACHE环境变量避免 ccache 干扰编译数据库内容。6.1 Rust 开发链接 ONDK 工具链ONDK./build.py ndk安装的那个捆绑了完整 Rust 工具链因此构建本身无需任何 Rust 前置配置。但若要开发 Rust 代码文档建议在 rustup 中把 ONDK 工具链登记为名为magisk的 toolchain 并设为默认# Link the ONDK toolchain with the name magisk rustup toolchain link magisk $ANDROID_HOME/ndk/magisk/toolchains/rust # Set magisk as default rustup default magisk工具链路径$ANDROID_HOME/ndk/magisk/toolchains/rust与 scripts/env.py#L47 中rust_sysroot的定义完全一致。此设置后VSCode 安装 rust-analyzer 插件即可正常工作。6.2 JetBrains IDE 的 rustup-wrapper 方案JetBrains 系 IDERustRover 或带 Rust 插件的其他 IDE需要额外两步。原因是 rustup 的 toolchain 解析方式与 IDE 的期望不匹配项目为此内置了一个 wrapper# 1) 安装 nightly 并补齐组件仅用于骗过 IDE实际编译仍走 wrapper 内的 magisk 工具链 rustup toolchain install nightly rustup nightly component add rust-src clippy # 2) 创建 wrapper 目录文档示例使用 ~/.cargo/wrapper ./build.py rustup ~/.cargo/wrappersetup_rustup()build.py#L525-L551的实现是清空目标 wrapper 目录把$CARGO_HOME/bin缺省~/.cargo/bin下所有 rustup 代理可执行文件以符号链接形式复制进 wrapper 目录然后编译 tools/rustup-wrapper 这个小型 Rust 工具用它替换 wrapper 目录中的rustup本体。之后在 IDE 的Settings Rust Toolchain location中填入该 wrapper 目录路径即可IDE 随即可用rustfmt与Clippy后者可直接用./build.py clippy在仓库层面运行build.py#L472-L493 会对每个目标 triple 分别检查 debug/release 两种 profile。补充仓库的 AGENTS.md 亦约定绕过build.py直接执行./gradlew、cargo、rustc、ndk-build等独立工具时必须以 scripts/env.py 作为前缀如scripts/env.py ./gradlew assembleDebug因为该脚本在直接执行时会完成ensure_cargo()/ensure_jdk()的环境注入scripts/env.py#L163-L167。七、签名与分发Signing and Distribution文档Signing and Distribution一节阐述了 Magisk 独有的签名信任机制与三个要点运行时签名校验release 版中对 Magisk APK 签名所用的证书会作为基准被 Magisk root 守护进程用来拒绝并强制卸载签名不匹配的 Magisk 应用以此保护用户免受仿冒/未经验证 APK 的侵害。App 侧的签名处理相关实现集中在 app/core/src/main/java/com/topjohnwu/magisk/core/signing/ 与 app/core/src/main/java/com/topjohnwu/magisk/core/utils/Keygen.kt从源码结构看Keygen 负责从内置 keystore 生成/维护签名材料开发时关闭校验对 Magisk 本身做开发调试时需切换为官方 debug 构建并重新安装从而关闭签名检查-r缺省即 debug 构建自签分发分发自己签名的构建时在config.prop中设置签名四元组keyStore/keyStorePass/keyAlias/keyPasskey 生成方式参考 Google 官方文档keytool 流程。Gradle 侧的消费点在 app/build-logic/src/main/java/Setup.ktsetupAppCommon()在Config[keyStore]存在时创建名为config的 signingConfig并让 debug 与 release 两种构建类型都优先使用它未配置签名时回退到默认debugkeystore。这解释了为何开发构建debug 签名与release 官方签名在设备上的信任行为完全不同——设备上守护进程认的是证书指纹而不是构建类型标签。八、实用扩展模拟器开发与 AVD 镜像修补build.py还提供了文档callbuild.pyto see your options所涵盖的两类开发辅助动作值得了解# 构建可选 -b 先构建并推送到模拟器运行 scripts/live_setup.sh 完成开发环境注入 ./build.py emulator [-b] [apk] # 修补 AVD 的 ramdisk.img 或 init_boot.img走 scripts/host_patch.sh产物为 input.magisk ./build.py avd_patch image output [--apk apk] [-b]setup_avd()build.py#L591-L599会自动从 APK 中提取lib/abi/libbusybox.so作为 busybox连同scripts/live_setup.sh一起 push 到/data/local/tmp执行patch_avd_file()build.py#L601-L624则把目标镜像 push 进设备、用设备内 busybox 完成修补后再 pull 回宿主机。这两条路径使开发者无需真机即可验证 init/magiskboot 相关改动。九、构建产物与清理输出目录默认out/all构建后包含app-debug|release.apk、stub-debug|release.apk、test.apk以及native/out/abi/下的五个原生目标二进制./build.py clean [targets...]支持按native删native/out与 elf-cleaner target、cpp删native/libs、native/obj、rust删native/out/rust及 FFI 生成文件、app执行:clean清理不传参则全清。注意clean rust会删除构建期生成的native/src/boot/proto/mod.rs等 proto 生成物build.py#L397-L403因此清理 Rust 后需要重新完整构建以重建绑定。小结Magisk 的构建体系以 build.py 为单一编排入口强绑定 ONDK r30.1 定制工具链Rust 静态库 ndk-build C/C 链接 elf-cleaner 收尾的 native 管线与Gradle 多模块 config.prop/gradle.properties 配置注入的 app 管线并行再通过config.prop的签名四元组与运行时守护进程签名校验形成从构建到分发的完整信任链。按本文第二至六节的步骤即可完成从环境搭建到 IDE 化日常开发的全部准备。【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考