从零学会 Magisk 模块开发最小结构、打包清单与安装验证完整指南【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/MagiskMagisk 模块开发说白了就是给已 Root 的 Android 设备制作一个系统文件替换包不改 ROM、不重编译系统就能替换系统文件、添加工具、修改属性重启即生效不想用还能随时移除。本文面向第一次做模块的新手带你做出一个最小可安装的模块 ZIP并给出打包检查清单、模块安装验证步骤以及模块不显示的排查路径。一、先看结论模块就是一个系统文件替换包Magisk 模块的工作方式很简单安装后整个模块目录会被放到/data/adb/modules/模块ID/其中system/子目录里的文件会在开机时叠加overlay到真实的系统分区上——你放进system/fonts/的字体文件会盖住系统自带的同名字体而真实的系统分区始终没有被写入。理解了这一点你就能快速判断一个需求能不能用模块实现要替换/新增系统分区里的文件字体、图标、bin 工具、配置文件→ 模块可以实现要修改内核、boot 镜像本身 → 不属于模块的领域要拦截或改写应用进程行为 → 需要进阶的 Zygisk 原生模块建议先做完基础模块再碰另一个关键优点是可逆模块可以随时禁用或彻底卸载不会像刷 ROM 那样动不了。二、最小模块文件结构4 个文件就够一个能装上的最小模块 ZIP根目录只需要这些module.prop # 必需模块的身份证 system/ # 核心会叠加到系统分区的目录 bin/xxx # 例如要新增的可执行文件 post-fs-data.sh # 可选早期启动脚本 service.sh # 可选后期启动脚本只有module.prop和system/模块就已经完整可用两个 sh 脚本按需添加。打包时注意ZIP 解压后第一层就是 module.prop不要再套一层文件夹否则安装程序会把外层目录名当成模块 ID导致识别失败。进阶一点在customize.sh里声明REPLACE目录/可以做整目录替换Magisk 会在模块对应目录放置一个.replace标记文件挂载时该目录整体被替换而不是逐文件合并REMOVE文件则把目标文件变成空节点相当于不写系统分区就删掉文件。三、module.prop 里不能写错的字段module.prop必须放在 ZIP 根目录它决定模块能否被识别。核心字段如下idmy_first_module name我的第一个模块 version1.0.0 versionCode1 author你的名字 description添加常用工具三个必须注意的点id 一旦确定就不要改。它就是模块的文件夹名也是 Magisk 识别模块的唯一依据改了 id 等于新装了一个模块旧的会残留在设备里。versionCode 必须是整数应用用它做版本比较写错会导致更新判断异常。ZIP 里没有 module.prop 会被直接拒绝安装逻辑会报 This zip is not a Magisk module!——这是最常见的打包错误信号。⚠️判断成功的标准装完重启后在 Magisk 应用的模块页面能看到 name、version、author说明字段都读对了。四、post-fs-data.sh 和 service.sh 该写哪个两个脚本的执行时机完全不同选错会导致脚本没跑完系统就继续启动或白等脚本执行时机是否阻塞适合干什么post-fs-data.sh系统分区挂载后、Zygote 启动前是该阶段整体约 35 秒超时超时后不再阻塞修文件权限、准备目录、改 SELinux 上下文service.sh系统服务启动后否后台执行等 boot_completed 后启动常驻服务、写日志如果模块只需要开机跑一次小任务通常放service.sh并自己等启动完成#!/system/bin/sh MODDIR${0%/*} while [ $(getprop sys.boot_completed) ! 1 ]; do sleep 1; done mkdir -p $MODDIR/logs这段脚本做什么等系统启动完成创建模块自己的日志目录。它放在 ZIP 根目录即service.sh。判断成功重启后该目录存在日志里有你写入的内容。两条硬性约定用${0%/*}取模块路径不要硬编码/data/adb/modules/...避免路径变化导致脚本失效涉及改属性的操作尽量放在 boot_completed 之后别影响开机。五、Magisk 模块打包前的检查清单Magisk 模块打包这一步决定安装成败打包前逐项过一遍绝大多数安装失败都能在这一步拦住ZIP 根目录第一层就是module.prop无外层文件夹id只含字母、数字、-、_、.且你打算长期使用它需要叠加的文件都在system/下放别处不会被挂载可执行文件权限 0755、普通文件 0644安装器会设置默认权限需要细调可在 customize.sh 里用set_perm脚本首行是#!/system/bin/sh想支持 Recovery 刷入ZIP 内含META-INF/com/google/android/update-binary可用本仓库 scripts/module_installer.sh 的内容和单行内容为#MAGISK的updater-script普通调试建议优先走应用内安装Recovery 刷机留给最终分发问题更少。六、模块安装与验证装完检查这三个位置安装方式任选其一Magisk 应用 → 模块 → 从存储安装推荐出错会有明确提示Root 后的终端执行magisk --install-module /sdcard/my_first_module.zip安装后重启按顺序检查这三个位置应用模块列表能看到模块名和版本点进详情有作者信息 → 识别成功文件层面ls /data/adb/modules/my_first_module应看到system子目录与脚本再确认被叠加的文件在系统里可见行为层面模块声明的属性用getprop查询脚本产物看自己的日志文件安装前也可以先在应用主界面确认设备状态正常方便和安装后的状态做对比回退与移除临时停用可touch /data/adb/modules/my_first_module/disable后重启彻底移除可在应用内卸载或touch remove标记后重启有 uninstall.sh 的话会先执行它。七、模块不显示 / 不生效怎么排查按这个顺序查基本能定位大多数问题列表里根本没有模块→ 先确认 ZIP 结构第一层是 module.prop和 id 是否合规应用内安装看报错Recovery 刷机看刷入日志。列表里有但文件没生效→ 多半是文件没放在system/下或该目录被声明为整目录替换.replace部分文件没有参与合并。脚本没执行→ 用logcat过滤模块名看开机日志确认脚本是否被调度post-fs-data 阶段有约 35 秒超时重活挪去 service.sh。装完直接开不了机→ 重启进入安全模式Safe ModeMagisk 会自动禁用所有模块先确认是模块问题再逐个排查。八、进阶方向与仓库内可查资料基础模块跑通之后可以按需求往三个方向走Zygisk 模块在模块下加zygisk/目录放原生库实现应用进程级注入与拦截属进阶内容动手前建议先看官方指南与示例代码SELinux 规则模块内放sepolicy.rule可自定义策略UI 交互action.sh让模块在应用里提供按钮触发的动作仓库内可直接查阅的资料相对路径官方模块开发指南docs/guides.mdRecovery 安装脚本scripts/module_installer.sh挂载与脚本执行逻辑源码native/src/core/module.rs、native/src/core/scripting.cpp细节行为如脚本超时时长随版本可能有调整建议以仓库当前源码与官方文档为准。【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从零学会 Magisk 模块开发：最小结构、打包清单与安装验证完整指南
从零学会 Magisk 模块开发最小结构、打包清单与安装验证完整指南【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/MagiskMagisk 模块开发说白了就是给已 Root 的 Android 设备制作一个系统文件替换包不改 ROM、不重编译系统就能替换系统文件、添加工具、修改属性重启即生效不想用还能随时移除。本文面向第一次做模块的新手带你做出一个最小可安装的模块 ZIP并给出打包检查清单、模块安装验证步骤以及模块不显示的排查路径。一、先看结论模块就是一个系统文件替换包Magisk 模块的工作方式很简单安装后整个模块目录会被放到/data/adb/modules/模块ID/其中system/子目录里的文件会在开机时叠加overlay到真实的系统分区上——你放进system/fonts/的字体文件会盖住系统自带的同名字体而真实的系统分区始终没有被写入。理解了这一点你就能快速判断一个需求能不能用模块实现要替换/新增系统分区里的文件字体、图标、bin 工具、配置文件→ 模块可以实现要修改内核、boot 镜像本身 → 不属于模块的领域要拦截或改写应用进程行为 → 需要进阶的 Zygisk 原生模块建议先做完基础模块再碰另一个关键优点是可逆模块可以随时禁用或彻底卸载不会像刷 ROM 那样动不了。二、最小模块文件结构4 个文件就够一个能装上的最小模块 ZIP根目录只需要这些module.prop # 必需模块的身份证 system/ # 核心会叠加到系统分区的目录 bin/xxx # 例如要新增的可执行文件 post-fs-data.sh # 可选早期启动脚本 service.sh # 可选后期启动脚本只有module.prop和system/模块就已经完整可用两个 sh 脚本按需添加。打包时注意ZIP 解压后第一层就是 module.prop不要再套一层文件夹否则安装程序会把外层目录名当成模块 ID导致识别失败。进阶一点在customize.sh里声明REPLACE目录/可以做整目录替换Magisk 会在模块对应目录放置一个.replace标记文件挂载时该目录整体被替换而不是逐文件合并REMOVE文件则把目标文件变成空节点相当于不写系统分区就删掉文件。三、module.prop 里不能写错的字段module.prop必须放在 ZIP 根目录它决定模块能否被识别。核心字段如下idmy_first_module name我的第一个模块 version1.0.0 versionCode1 author你的名字 description添加常用工具三个必须注意的点id 一旦确定就不要改。它就是模块的文件夹名也是 Magisk 识别模块的唯一依据改了 id 等于新装了一个模块旧的会残留在设备里。versionCode 必须是整数应用用它做版本比较写错会导致更新判断异常。ZIP 里没有 module.prop 会被直接拒绝安装逻辑会报 This zip is not a Magisk module!——这是最常见的打包错误信号。⚠️判断成功的标准装完重启后在 Magisk 应用的模块页面能看到 name、version、author说明字段都读对了。四、post-fs-data.sh 和 service.sh 该写哪个两个脚本的执行时机完全不同选错会导致脚本没跑完系统就继续启动或白等脚本执行时机是否阻塞适合干什么post-fs-data.sh系统分区挂载后、Zygote 启动前是该阶段整体约 35 秒超时超时后不再阻塞修文件权限、准备目录、改 SELinux 上下文service.sh系统服务启动后否后台执行等 boot_completed 后启动常驻服务、写日志如果模块只需要开机跑一次小任务通常放service.sh并自己等启动完成#!/system/bin/sh MODDIR${0%/*} while [ $(getprop sys.boot_completed) ! 1 ]; do sleep 1; done mkdir -p $MODDIR/logs这段脚本做什么等系统启动完成创建模块自己的日志目录。它放在 ZIP 根目录即service.sh。判断成功重启后该目录存在日志里有你写入的内容。两条硬性约定用${0%/*}取模块路径不要硬编码/data/adb/modules/...避免路径变化导致脚本失效涉及改属性的操作尽量放在 boot_completed 之后别影响开机。五、Magisk 模块打包前的检查清单Magisk 模块打包这一步决定安装成败打包前逐项过一遍绝大多数安装失败都能在这一步拦住ZIP 根目录第一层就是module.prop无外层文件夹id只含字母、数字、-、_、.且你打算长期使用它需要叠加的文件都在system/下放别处不会被挂载可执行文件权限 0755、普通文件 0644安装器会设置默认权限需要细调可在 customize.sh 里用set_perm脚本首行是#!/system/bin/sh想支持 Recovery 刷入ZIP 内含META-INF/com/google/android/update-binary可用本仓库 scripts/module_installer.sh 的内容和单行内容为#MAGISK的updater-script普通调试建议优先走应用内安装Recovery 刷机留给最终分发问题更少。六、模块安装与验证装完检查这三个位置安装方式任选其一Magisk 应用 → 模块 → 从存储安装推荐出错会有明确提示Root 后的终端执行magisk --install-module /sdcard/my_first_module.zip安装后重启按顺序检查这三个位置应用模块列表能看到模块名和版本点进详情有作者信息 → 识别成功文件层面ls /data/adb/modules/my_first_module应看到system子目录与脚本再确认被叠加的文件在系统里可见行为层面模块声明的属性用getprop查询脚本产物看自己的日志文件安装前也可以先在应用主界面确认设备状态正常方便和安装后的状态做对比回退与移除临时停用可touch /data/adb/modules/my_first_module/disable后重启彻底移除可在应用内卸载或touch remove标记后重启有 uninstall.sh 的话会先执行它。七、模块不显示 / 不生效怎么排查按这个顺序查基本能定位大多数问题列表里根本没有模块→ 先确认 ZIP 结构第一层是 module.prop和 id 是否合规应用内安装看报错Recovery 刷机看刷入日志。列表里有但文件没生效→ 多半是文件没放在system/下或该目录被声明为整目录替换.replace部分文件没有参与合并。脚本没执行→ 用logcat过滤模块名看开机日志确认脚本是否被调度post-fs-data 阶段有约 35 秒超时重活挪去 service.sh。装完直接开不了机→ 重启进入安全模式Safe ModeMagisk 会自动禁用所有模块先确认是模块问题再逐个排查。八、进阶方向与仓库内可查资料基础模块跑通之后可以按需求往三个方向走Zygisk 模块在模块下加zygisk/目录放原生库实现应用进程级注入与拦截属进阶内容动手前建议先看官方指南与示例代码SELinux 规则模块内放sepolicy.rule可自定义策略UI 交互action.sh让模块在应用里提供按钮触发的动作仓库内可直接查阅的资料相对路径官方模块开发指南docs/guides.mdRecovery 安装脚本scripts/module_installer.sh挂载与脚本执行逻辑源码native/src/core/module.rs、native/src/core/scripting.cpp细节行为如脚本超时时长随版本可能有调整建议以仓库当前源码与官方文档为准。【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考