KernelSU 模块开发入门——module.prop 脚本与 system 目录规则

从 Magisk 开发经验迁移

KernelSU 模块格式与 Magisk 几乎一致：zip 打包、装到 /data/adb/modules、systemless 修改。post-fs-data.sh、service.sh、system.prop、sepolicy.rule 的执行时机与语义完全相同，BusyBox 独立模式也一样（KernelSU 直接使用 Magisk 项目编译的 BusyBox 二进制）。熟悉 Magisk 的开发者只补差异即可。

必须记住的差异清单

1. 模块不支持在 Recovery 中安装；
2. 无内置 Zygisk：需要 ZygiskNext（见 Zygisk 模块支持）；
3. 挂载由元模块承担：带 system 目录的模块要求用户装了元模块（如 meta-overlayfs），脚本类功能不受影响（见 元模块架构）；
4. 不支持 .replace 文件：删除系统文件用 mknod filename c 0 0 触发 whiteout；KernelSU 提供 REMOVE 与 REPLACE 变量简化操作：

   REMOVE=" /system/app/YouTube /system/app/Bloatware "
   REPLACE=" /system/app/YouTube "

写在 customize.sh 里，安装器自动执行对应 mknod / opaque 目录操作；

1. BusyBox 路径不同：/data/adb/ksu/bin/busybox（Magisk 在 /data/adb/magisk/busybox），此为内部行为未来可能变；
2. 新增两种脚本：post-mount.sh（挂载完成后）与 boot-completed.sh（系统启动完毕）；
3. 环境变量区分宿主：脚本里 KSU 变量为 true 即在 KernelSU 下；不要用 MAGISK_VER 判断（它在 KernelSU 里恒为 25.2 的值）。

module.prop 骨架

id=a_module
name=示例模块
version=1.0.0
versionCode=1
author=你的名字
description=模块做什么

id 必须匹配 ^[a-zA-Z][a-zA-Z0-9._-]+$ 且发布后不改；versionCode 必须为整数；文件用 LF 换行。可选的 actionIcon / webuiIcon 指定管理器里动作与 WebUI 的快捷图标。

脚本环境要点

• customize.sh 支持 SKIPUNZIP=1 完全自管解压；可用变量有 KSU_VER、ARCH、API、IS64BIT 等，可用函数有 ui_print、abort、set_perm 等；
• 模块脚本内用 MODDIR=${0%/*} 取自身路径，不要硬编码；
• post-fs-data 阶段禁止 setprop（会死锁），改用 resetprop -n；
• 大多数模块只需要 service.sh。

发布前自测

在干净的 KernelSU 环境装一遍；验证有/无元模块两种环境下的行为（无元模块时脚本应正常、挂载可缺失）；确认卸载逻辑（uninstall.sh）能清理干净。initrc 注入与 WebUI 属进阶能力，见 模块 WebUI 与配置系统。