KernelSU模块开发完全指南

唐妮琪Plains

于 2025-06-03 09:04:37 发布

阅读量406

点赞数 4

本文链接：https://blog.csdn.net/gitblog_01163/article/details/148392826

版权

KernelSU模块开发完全指南

KernelSU A Kernel based root solution for Android 项目地址: https://gitcode.com/gh_mirrors/ke/KernelSU

前言

KernelSU作为一款基于内核的root解决方案，其模块机制允许开发者在不修改系统分区的情况下实现对系统目录的修改，这种技术通常被称为"systemless"（无系统修改）技术。本文将全面解析KernelSU模块的开发要点，帮助开发者快速掌握模块开发技巧。

模块机制概述

KernelSU的模块机制与Magisk模块高度相似，但底层实现有所不同。模块通过OverlayFS技术实现对系统目录的覆盖，所有修改都在内存中完成，不会实际修改系统分区内容。这种机制带来了以下优势：

系统分区保持完整性，避免因修改导致的OTA更新失败
模块可以随时启用或禁用，修改可即时生效
多个模块可以协同工作，修改不会相互冲突

模块目录结构详解

一个标准的KernelSU模块目录结构如下：

/data/adb/modules
└── 模块ID
    ├── module.prop        # 模块元数据配置文件
    ├── system            # 系统覆盖目录
    │   └── ...           # 需要覆盖的系统文件
    ├── skip_mount        # 存在则跳过system目录挂载
    ├── disable           # 存在则禁用模块
    ├── remove           # 存在则下次重启移除模块
    ├── post-fs-data.sh   # post-fs-data阶段执行的脚本
    ├── service.sh        # late_start阶段执行的脚本
    ├── system.prop       # 系统属性配置文件
    └── sepolicy.rule    # 自定义SELinux规则

module.prop文件规范

module.prop是模块的身份证，必须包含以下字段：

id=模块唯一标识符  # 必须字母开头，仅包含字母数字和._-
name=模块显示名称
version=版本名称
versionCode=数字版本号
author=作者信息
description=模块描述

注意：id字段一旦确定不应更改，它是模块的唯一标识符。

系统文件覆盖机制

KernelSU通过OverlayFS实现系统文件的无损修改，开发者需要了解以下核心概念：

文件覆盖：在模块的system目录下放置同名文件即可覆盖系统文件
文件删除：使用mknod 文件名 c 0 0创建特殊文件表示删除
目录替换：使用setfattr -n trusted.overlay.opaque -v y 目录名标记完整替换

为了方便操作，可以在customize.sh中使用REMOVE和REPLACE变量：

# 删除系统文件/目录
REMOVE="
/system/app/UnwantedApp
/system/priv-app/Bloatware
"

# 替换系统目录
REPLACE="
/system/app/NewApp
/system/etc/config
"

脚本开发指南

脚本执行环境

所有模块脚本都在BusyBox的ash shell中执行，并启用了Standalone模式，这意味着：

所有命令默认使用BusyBox内置实现
环境变量MODDIR=${0%/*}可获取模块目录
可通过KSU=true判断运行环境为KernelSU

脚本类型与执行时机

| 脚本类型 | 执行阶段 | 特点 | |---------|---------|------| | post-fs-data.sh | post-fs-data | 阻塞执行，Zygote启动前 | | service.sh | late_start | 非阻塞，与系统并行启动 | | boot-completed.sh | 启动完成 | 收到BOOT_COMPLETED广播后 | | post-mount.sh | OverlayFS挂载后 | 系统目录覆盖完成后 |

最佳实践：大多数模块应使用service.sh，仅在需要早期初始化的场景使用post-fs-data.sh。

模块安装包制作

模块安装包是一个包含模块文件的ZIP压缩包，其中可以包含：

模块所有文件
customize.sh（可选安装定制脚本）
其他资源文件

customize.sh脚本开发

customize.sh在安装过程中被调用，可用于：

根据设备ABI选择不同文件
设置特殊文件权限
完全自定义安装流程（设置SKIPUNZIP=1）

可用变量和函数：

# 常用变量
MODPATH=/data/adb/modules/模块ID
ARCH=arm64 # 设备架构
API=30    # Android API级别

# 实用函数
ui_print "安装信息"  # 显示安装信息
abort "错误信息"    # 终止安装
set_perm 文件 用户 组 权限 [SELinux上下文]