KernelSU meta-overlayfs 快速上手：模块装了不生效，先装好这个再谈挂载
【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU
先说一个最常见的症状：模块装好了，重启也重启了，脚本在跑，sepolicy 和 system.prop 都生效，唯独你想覆盖的/system文件还是原装的。问题基本可以锁定在这里——KernelSU 本身不做模块挂载，挂载这件事被下放给一个叫元模块（metamodule，负责模块挂载的插件组件）的附加组件，而全新安装的 KernelSU 默认没有任何元模块，模块的 system 目录自然永远不会叠到系统分区上。官方参考实现就是meta-overlayfs，下面把它从判断、安装到验证、排错的完整路径走一遍。
症状倒推：模块装了，到底卡在哪
按模块用到的东西分三条线排查：
- 只用
post-fs-data.sh、service.sh这类脚本 → 不依赖挂载，不用查挂载链路 - 用了 system 目录（覆盖文件、去预装、整目录替换）→ 必须确认元模块已激活
- 元模块明明在列表里、也重启过，唯独某个模块不生效 → 去该模块目录找
skip_mount（跳过挂载）和disable（禁用模块）两个标记文件，存在就删掉，再重启
website/docs/guide/faq.md 里"为什么全新安装后模块不工作"给出的结论和上面一致：挂载相关的失效，九成是元模块缺失或标记文件在挡路。
动手前先判断：你的模块到底需不需要挂载
meta-overlayfs只对一种场景有意义——模块的改动落在系统分区上。对照一下：
- 模块里带 system 目录 → 必须装。挂载后它会被叠加到 system、vendor、product、system_ext、odm、oem 六个分区
- 只有 shell 脚本 → 不需要，脚本独立执行
sepolicy.rule→ 不需要，由 KernelSU 核心直接加载system.prop→ 不需要，直接作为系统属性载入
只用到后三样就可以跳过后面所有步骤。模块目录的完整结构参考 website/docs/guide/module.md。
三步装完 meta-overlayfs 并重启
装之前先确认设备上没有其他激活的元模块——KernelSU 同一时间只允许一个，装第二个会被直接拦下，这是防止两套挂载方案打架的单实例限制。
- 下载
meta-overlayfs.zip安装包 - 打开 KernelSU Manager，点右下角悬浮按钮（➕）
- 选中刚下载的 zip，确认安装，然后重启设备
重启后不需要任何手动操作：在 post-fs-data（文件系统就绪）阶段，元模块的挂载脚本自动执行，把各模块的 system 目录以 systemless（只叠加在表面、不改动原始分区）的方式叠到对应分区上——相当于贴了层随时能撕的膜，底下的/system原封不动。
重启之后，用四个检查确认挂载真的生效
- 打开 Module 页面：meta-overlayfs 出现在列表里，且带元模块专属标识
- 执行
ls -l /data/adb/metamodule：这个符号链接应指向元模块目录，与 ID 无关，排查"当前激活的是谁"最直接 - 覆盖验证：模块里与系统同名的文件，读取到的应是模块侧内容
- 删除验证：用
mknod filename c 0 0生成一个同名零字节占位符，OverlayFS 会把原文件当作 whiteout（用空占位符让原文件"看起来没了"）处理，原文件不可见而分区本身未变
整目录替换还有两条路：对模块内同名目录执行setfattr -n trusted.overlay.opaque -v y <TARGET>打上 opaque（不合并的不透明目录）标记，该目录就只保留模块自己的内容；或者偷懒，在customize.sh里声明REMOVE/REPLACE列表，KernelSU 会自动替你把 mknod 和 opaque 标记做掉。
切换与卸载前，绕开两个雷区
想换成别的元模块，单实例约束下唯一路径是：
- 卸载所有普通模块
- 卸载当前元模块
- 重启
- 安装新的元模块
- 重装普通模块
- 再重启一次
卸载元模块后所有模块立即失去挂载能力，设备能正常开机，但在装回新元模块之前，任何模块改动都不会生效
所以不换就别轻易动它。如果真踩了坑导致全部模块罢工，最快的恢复动作就是装一个新的元模块。官方对执行顺序、符号链接机制和单实例约束的完整说明见 website/docs/guide/metamodule.md。
现在就去 Module 页面确认 meta-overlayfs 出现在列表里，带标识的那一个。
【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
