KernelSU 与 Magisk 对比全解析模块兼容开发实战指南【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSUKernelSU 与 Magisk 的模块机制在表面上高度相似但由于两者底层实现机制完全不同模块在文件替换、挂载架构、执行阶段等方面存在显著差异。本文以 KernelSU 官方文档为骨架结合仓库源码userspace/ksud 与 website/docs/guide深入剖析这些异同帮助你写出能在两个环境中同时稳定运行的兼容模块。为什么必须理解这些差异KernelSU 与 Magisk 的模块虽然都通过/data/adb/modules目录组织但两者的挂载引擎、安装器与生命周期脚本执行顺序并不一致。如果希望你的模块同时兼容 Magisk 与 KernelSU就必须精确掌握两套机制的异同否则会出现在 Magisk 上正常、在 KernelSU 上失效的兼容性问题。好在两个平台都提供了明确的运行时环境标识让模块脚本可以自行区分当前运行环境。如何区分模块运行在 KernelSU 还是 MagiskKernelSU 文档明确指出在所有可以执行模块脚本的位置customize.sh、post-fs-data.sh、service.sh、boot-completed.sh、post-mount.sh等都可以通过环境变量KSU来区分运行环境。在 KernelSU 中该变量会被设置为true。这一行为有明确的源码依据。module.rs 的 get_common_script_envs 函数 在构建脚本执行环境时固定注入了以下变量(ASH_STANDALONE, 1.to_string()), (KSU, true.to_string()), (KSU_KERNEL_VER_CODE, ksucalls::get_version().to_string()), (KSU_VER_CODE, defs::VERSION_CODE.to_string()), (KSU_VER, defs::VERSION_NAME.to_string()), (KSU_UAPI_VER, ksucalls::uapi_version().to_string()), (KSU_RUNTIME_MODE, ksucalls::runtime_mode().to_string()),此外还有条件注入的KSU_MODULE当前模块 ID与KSU_LATE_LOAD延迟加载场景。因此在脚本中可以用如下模式写出双兼容逻辑if [ $KSU true ]; then ui_print - 当前运行在 KernelSU 环境 (KSU_VER$KSU_VER) else ui_print - 当前运行在 Magisk 环境 fiKernelSU 与 Magisk 的共同点尽管实现机制不同KernelSU 在设计上刻意保持了与 Magisk 模块格式的高度兼容。以下共同点是两个平台模块通用的部分兼容模块可以直接复用维度说明模块文件格式两者均使用 ZIP 格式组织模块模块格式几乎完全一致安装目录两者都位于/data/adb/modulesSystemless两者都支持以无系统修改systemless的方式修改/systempost-fs-data.sh执行时机与语义完全相同service.sh执行时机与语义完全相同system.prop完全一致均由 resetprop 机制加载sepolicy.rule完全一致均用于注入自定义 SELinux 策略BusyBox脚本均在开启独立模式Standalone Mode的 BusyBox 中执行关于最后一点module.rs 中ASH_STANDALONE1的注入即是 KernelSU 启用 BusyBox Standalone 模式的实现方式。所谓 Standalone 模式是指 BusyBox 的ashshell 中执行的每一条命令都会直接调用 BusyBox 内置 applet而不依赖PATH中的系统命令从而保证脚本在任何 Android 版本上都有确定、完整的命令集合。需要强制绕过 BusyBox 时只能使用完整路径调用可执行文件。值得一提的是KernelSU 的 BusyBox 二进制直接编译自 Magisk 项目因此两者脚本层面的 BusyBox 兼容性无需担心。KernelSU 与 Magisk 的核心差异以下是模块开发者必须注意的差异点它们直接决定了模块的安装与运行行为。1. Recovery 模式安装KernelSU 模块不支持在 Recovery 模式下安装。这与 KernelSU 的安装器设计有关安装流程依赖运行中的系统环境与 ksud 用户态程序协作完成而非独立于系统的 Recovery 脚本。installer.sh 中的安装逻辑以BOOTMODE变量区分场景但 KernelSU 的模块安装主要面向已启动的 Android 系统通过 KernelSU Manager 应用或 ksud 命令行。2. Zygisk 支持KernelSU没有内置 Zygisk 支持因此标准模块中不存在 Zygisk 相关内容。如果需要运行 Zygisk 模块可以借助社区项目 ZygiskNext 来提供 Zygisk 兼容层。在通过 ZygiskNext 支持的情况下Zygisk 模块的内容与 Magisk 所支持的完全一致。模块开发者无需为 KernelSU 单独适配 Zygisk 模块内容。3. 模块挂载架构metamodule 机制最重要的架构差异这是两者最根本的架构区别Magisk挂载逻辑内置于其核心中模块安装后由核心自动完成 systemless 挂载。KernelSU采用 metamodule元模块架构将挂载能力从核心剥离委派给可插拔的 metamodule例如官方参考实现meta-overlayfs。KernelSU 需要先安装一个 metamodule 才能启用模块挂载功能。该架构的意图是降低内核被检测的攻击面、保持核心稳定同时允许社区发展多样化的挂载实现OverlayFS、Magic mount、FUSE 自定义实现甚至完全不做挂载。对用户而言全新安装的 KernelSU 必须安装一个 metamodule如meta-overlayfs否则所有模块的system目录都不会被挂载。模块的脚本、sepolicy 规则、system.prop 等功能则不需要 metamodule 即可工作。对模块开发者而言只要用户安装了兼容的 metamodule现有模块无需任何代码改动即可继续工作——meta-overlayfs 提供了与 Magisk 兼容的挂载语义。若你的模块仅包含脚本而无需修改系统文件则连 metamodule 都不需要。⚠️ 注意事项卸载当前 metamodule 会影响所有模块的挂载需谨慎操作同一时刻只允许安装一个 metamodule。4. 文件替换与删除方式.replace与REMOVE/REPLACEKernelSU不支持 Magisk 风格的.replace目录标记取而代之的是两种方式方式一mknod创建同名字符设备文件要删除目标文件需要在模块对应路径下用以下命令创建同名文件mknod filename c 0 0即创建一个主设备号/次设备号为 0/0 的字符设备节点挂载层据此判定应删除目标路径下的对应文件。这与 installer.sh 中的 mark_remove 函数 的实现完全一致mark_remove() { mkdir -p ${1%/*} 2/dev/null mknod $1 c 0 0 chmod 644 $1 }方式二REMOVE与REPLACE变量KernelSU 在安装脚本环境中支持REMOVE和REPLACE变量用于在安装阶段批量删除或替换文件/文件夹。installer.sh 中对应的处理逻辑如下# Handle replace folders for TARGET in $REPLACE; do ui_print - Replace target: $TARGET mark_replace $MODPATH$TARGET done # Handle remove files for TARGET in $REMOVE; do ui_print - Remove target: $TARGET mark_remove $MODPATH$TARGET done在customize.sh中声明这些变量即可例如# 删除 /system/bin/example 文件 REMOVE /system/bin/example # 替换删除后由模块内容接管/system/app/ExampleApp 目录 REPLACE /system/app/ExampleApp 注意安装阶段产生的删除标记会体现在模块目录中的remove文件上——defs.rs 定义了REMOVE_FILE_NAME remove而 module.rs 多处据此判断模块的挂载/清理行为。5. BusyBox 路径不同两个平台的 BusyBox 位置不同且 KernelSU 官方文档特别提醒这是 KernelSU 的内部行为未来可能变更KernelSU/data/adb/ksu/bin/busyboxMagisk/data/adb/magisk/busybox模块脚本中如需要显式调用 BusyBox应避免硬编码绝对路径或在使用前探测环境if [ $KSU true ]; then BB/data/adb/ksu/bin/busybox else BB/data/adb/magisk/busybox fi6. 新增生命周期阶段boot-completed.sh与post-mount.shKernelSU 在 Magisk 的post-fs-data.sh/service.sh基础上新增了两个生命周期脚本boot-completed.sh在 Android 系统启动完成后执行对应sys.boot_completed置位后的阶段。post-mount.sh在模块挂载完成后执行。这两个阶段在源码中有明确的调用实现。init_event.rs 在on_post_data_fs中调用run_stage(post-mount, true)阻塞式init_event.rs 在on_boot_completed中调用run_stage(boot-completed, false)非阻塞式。同时module.md 也确认了这两个脚本分别对应 post-mount 与 boot-completed 阶段。各阶段脚本的执行顺序以 init_event.rs 的run_stage为据为先执行公共.d目录脚本再执行 metamodule 的阶段脚本优先最后执行普通模块的阶段脚本。post-fs-data 阶段: 1. 公共 post-fs-data.d 脚本 2. 清理模块 / restorecon / 加载 sepolicy.rule 3. metamodule 的 post-fs-data.sh 4. 普通模块的 post-fs-data.sh 5. 加载 system.prop 6. metamodule 的 metamount.sh挂载所有模块 7. post-mount 阶段post-mount.d、metamodule post-mount.sh、普通模块 post-mount.sh service 阶段: 1. 公共 service.d 脚本 2. metamodule 的 service.sh 3. 普通模块的 service.sh boot-completed 阶段: 1. 公共 boot-completed.d 脚本 2. metamodule 的 boot-completed.sh 3. 普通模块的 boot-completed.sh 提示boot-completed.sh适合执行需要等待系统完全就绪的任务如等待属性sys.boot_completed1后的初始化post-mount.sh适合在挂载完成后对挂载结果做校验或补充操作。由于post-mount阶段是阻塞执行的脚本应保持轻量、快速退出避免拖慢开机流程。实战编写双兼容模块的检查清单综合以上异同编写同时兼容 KernelSU 与 Magisk 的模块时建议遵循以下清单环境探测优先所有脚本开头通过KSU环境变量分支处理不要假定运行平台。文件删除用变量在customize.sh中声明REMOVE/REPLACEKernelSU 语义不要依赖.replace目录同时可在customize.sh中按环境兼容处理 Magisk 的.replace标记。不硬编码 BusyBox 路径优先依赖 Standalone 模式下的命令环境必要时按平台探测路径。生命周期脚本语义对齐post-fs-data.sh与service.sh两平台语义一致可放心共用KernelSU 特有的boot-completed.sh/post-mount.sh在 Magisk 上不会执行涉及这些阶段的逻辑需自行做好降级。明确挂载前提如果模块包含system目录在文档中提示 KernelSU 用户需要安装 metamodule如meta-overlayfs纯脚本模块则无此要求。遵循 module.prop 规范id必须匹配^[a-zA-Z][a-zA-Z0-9._-]$且以字母开头versionCode必须为整数这是两个平台共同的识别基础。总结KernelSU 与 Magisk 的模块体系形似而神异模块格式、安装目录、post-fs-data.sh/service.sh/system.prop/sepolicy.rule语义完全一致这保证了绝大多数模块可以无缝迁移但挂载架构metamodule、文件替换方式mknod与REMOVE/REPLACE、BusyBox 路径、生命周期阶段boot-completed.sh/post-mount.sh以及 Recovery 安装与 Zygisk 支持上的差异则要求开发者以KSU环境变量为支点编写真正的双兼容逻辑。把握住本文梳理的这些差异你的模块就能稳定运行在两大 root 方案之上。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考