MagiskBoot 完整教程：3 个步骤解包、修改并重打包 boot 镜像
【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk
MagiskBoot 是 Magisk 项目自带的命令行工具（源码见 native/src/boot/），负责 Android 启动镜像修改：把 boot.img 拆成 kernel、ramdisk、dtb 等独立文件，改完再按原格式重打包。刷第三方内核、给 boot 分区注入 Magisk，本质都是这套 boot.img 解包重打包流程。这份 MagiskBoot 使用教程只写最短可跑通的路径。
boot.img 解包后能得到哪些文件
unpack解析镜像 header 后，把各 section 按名导出到当前目录；检测到压缩时会先解压再写盘，-n可跳过解压保留原始格式：
| 文件 | 内容 |
|---|---|
kernel | Linux 内核本体 |
kernel_dtb | 与内核打包在一起的设备树（部分机型才有） |
ramdisk.cpio | 初始内存文件系统，cpio 归档，Magisk 的注入点 |
dtb/extra/second | 独立设备树、附加数据、二级加载器（存在才导出） |
recovery_dtbo | recovery 的设备树 overlay（存在才导出） |
header | 加-h参数时导出，含 cmdline 等配置，repack 时可据此修改 |
GKI 一类把 DTB 嵌在image里的机型，拆出来的是image.*-dtb，还需要split命令拆成kernel和kernel_dtb两份。
三步主流程：unpack 解包、修改组件、repack 重打包
./magiskboot unpack boot.img ./magiskboot cpio ramdisk.cpio patch ./magiskboot repack boot.img new_boot.img- unpack：解析 header，导出全部组件，这是所有后续修改的基础。
- 修改：动 ramdisk 用
cpio子命令（ls、add MODE ENTRY FILE、rm、patch等，参数见 docs/tools.md）；换内核就替换kernel文件；改 cmdline 等就编辑header文件。 - repack：以原始镜像为模板重建，只更新 section 大小、校验和等必要字段，各组件按原格式重新压缩。注意它只读当前目录的文件，目录里有多余文件可能被打进新镜像；不指定输出名时默认生成
new-boot.img。
两个真实用途：注入 Magisk 与替换内核
给 boot 镜像注入 Magisk
目标：保留官方 boot 的内核与 cmdline，只改 ramdisk，拿到 root。
操作：
./magiskboot unpack boot.img ./magiskboot cpio ramdisk.cpio patch ./magiskboot repack boot.imgcpio patch应用 ramdisk 补丁，环境变量KEEPVERITY/KEEPEFORCEENCRYPT控制是否保留 verity 与强制加密；完整流程会先用cpio backup备份原始 ramdisk。Magisk App 里的 "Patch Image" 按钮内部走的正是同一套流程，手动执行的价值在于每一步都可控。刷入后在 Manager 首页确认 Ramdisk 状态为 Yes，即注入成功：
注意：先跑./magiskboot verify boot.img确认原镜像是否带 AVB 1.0 签名，启用 AVB 的机型改完后签名问题要单独处理。
替换自定义内核
目标：用第三方内核替换官方内核，其余组件原样保留。
操作：
./magiskboot unpack stock_boot.img # 用新内核覆盖当前目录的 kernel 文件 ./magiskboot repack stock_boot.img custom_boot.img注意：DTB 嵌在image里的机型必须先split拆出kernel和kernel_dtb，只替换kernel会把 DTB 弄丢；header 里的偏移、大小字段由 repack 自动重算，cmdline 不要顺手改，改了大概率开不了机。
翻车预防与自救：bootloop、刷错 slot、OTA 覆盖
| 现象 | 原因 | 处理 |
|---|---|---|
| unpack 报无效 header，返回码 3 | 文件不是标准 boot 镜像，可能是 vendor_boot 或拿错了分区 | 确认取的是官方固件里的 raw boot 分区，别用其他镜像文件试 |
| 重打包后 bootloop | 当前目录有无关文件被 repack 读入，或 header 字段被改动 | 在干净目录重新 unpack 再 repack；header 改动还原原值 |
| 刷入后系统仍跑旧 boot | A/B 设备刷错了 slot | 用 fastboot 查 active slot，刷对应的boot_a/boot_b |
| OTA 升级后 Magisk 没了 | 更新覆盖了你改过的分区，块校验失败 | 升级前在 App 里执行 "Restore Images"；A/B 设备 OTA 后用 "Install to Inactive Slot" 重装，流程见 docs/ota.md |
| 换了压缩格式后不启动 | 给已压缩的组件重复压缩，或算法与设备不匹配 | 交给 repack 按原格式自动压缩；-n仅在组件本身已是压缩格式时使用，支持 gzip/lz4/lzma/xz/bzip2 等 |
回滚方案：改坏了怎么刷回原镜像
动手前先留底，这是所有自救的前提：
cp boot.img boot_stock.img改坏后的标准动作，两条命令刷回去：
fastboot flash boot boot_stock.img fastboot rebootA/B 设备把分区名换成实际的boot_a/boot_b。如果当初是通过 App 安装的 Magisk，卸载对话框里的 "Restore Images" 会用安装时的备份把分区恢复成原厂状态，只移除 Magisk 的改动，不用电脑介入：
一句话备忘
- 先备份原始 boot.img，再碰任何文件
- 流程先在模拟器或备用机上验证一遍
- repack 只读当前目录，目录保持干净
- A/B 设备先确认 active slot 再刷
- 改 header、动压缩格式之前，先弄懂字段含义
【免费下载链接】MagiskThe Magic Mask for Android项目地址: https://gitcode.com/GitHub_Trending/ma/Magisk
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
