Magisk 首次安装实战：Boot Ramdisk 判定、镜像 Patch 流程与三星设备专属路径详解

本文围绕 Magisk 官方安装文档展开，系统讲解首次 root 的完整操作链路：如何判定设备 boot 分区是否含 ramdisk、如何获取并 Patch boot.img/init_boot.img/recovery.img、无 ramdisk 设备如何借用 recovery 分区，以及三星设备（Knox、RMM、AP tar 包）的特殊安装流程。读完后你可以独立完成一台设备的 Magisk 首次安装与卸载，并能从源码层面理解 Magisk 应用内“选择并修补文件”背后的实际执行逻辑。

一、安装前置条件与方式选择

Magisk 安装文档（docs/install.md）开篇给出三条硬性前置条件，三者缺一不可：

1. 你应当熟悉 adb 与 fastboot 的常用操作；
2. 如果你的设备还打算安装自定义内核，先装 Magisk，后装内核（后装的自定义内核会覆盖 boot 分区，导致 Magisk 失效）；
3. 设备的 bootloader 必须已解锁。

此外，文档给出一个重要的方式选择原则：如果设备上已经安装了 Magisk，强烈建议直接在 Magisk 应用内使用“直接安装”（Direct Install）方式升级，而不是重复走一遍首次安装流程。从源码可以印证这条建议的合理性：应用内的直接安装入口最终调用 MagiskInstaller.Direct，其执行链为 findImage() → extractFiles() → patchBoot() → flashBoot()，即自动定位当前 boot 分区、从当前设备自身的已 patch 镜像还原出原厂状态再重新 patch、最后直接写回分区，全程无需手工导出/刷写镜像，也避免了“跨设备 patch”这一最危险的错误。

二、判定设备是否拥有 Boot Ramdisk

安装最新版 Magisk 应用并打开首页，你会看到类似如下的设备信息界面：

其中 Ramdisk 一栏的结果决定后续安装路径：

• 有 ramdisk：目标是 boot.img（若设备存在 init_boot 分区，则目标是 init_boot.img）；
• 无 ramdisk：目标是 recovery.img，需要先阅读下文的“Magisk in Recovery”一节。

这些镜像可以从官方固件包或自定义 ROM 的 zip 包中提取。文档特别提醒：存在少数例外——某些设备（据文档所知主要是部分小米机型）的 bootloader 实际上会接受本不该存在的 ramdisk，此时无法自动探测，只能按“有 ramdisk”的流程实际尝试。

源码视角：Ramdisk 是如何判定的

应用首页展示的 Ramdisk 结论并非简单读属性，而是一段 shell 探测逻辑。scripts/app_functions.sh 中的 check_boot_ramdisk 函数判定规则为：

• 若设备是 A/B 结构（存在 slot 后缀），必然视为有 ramdisk；
• 若设备是“legacy SAR”（System-as-Root 且非 A/B），则视为无 ramdisk，并同时强制置位 RECOVERYMODE=true；
• 其余情况默认有 ramdisk。

app_init()（scripts/app_functions.sh）会把 SLOT、SYSTEM_AS_ROOT、RAMDISKEXIST、ISAB、CRYPTOTYPE、PATCHVBMETAFLAG、LEGACYSAR、RECOVERYMODE、KEEPVERITY、KEEPFORCEENCRYPT、VENDORBOOT 等变量一次性打印给应用，首页信息面板即由此而来。

为什么有无 Ramdisk 如此关键

要理解这一点，需回到 docs/boot.md 对 Android 启动方式的分类。按“最终 rootdir”划分，Magisk 关注的启动方法有三类：

方法	初始 rootdir	最终 rootdir	说明
A	rootfs	rootfs	传统 initramfs 启动
B	system	system	legacy SAR，内核直接挂载 system 分区
C	rootfs	system	2SI（Two Stage Init），Android 10+ 主流方式

对应到设备类型（docs/boot.md）：

• Type I / Type IV：boot 分区内含 ramdisk，Magisk 直接 patch boot 镜像即可；
• Type III（A-only + legacy SAR，文档称之为“对 Magisk 而言最糟糕的设备类型”）：boot 分区内没有 ramdisk，且内核不会去读你塞进去的 initramfs，Magisk 只能装进 recovery 分区——这正是“Magisk in Recovery”机制存在的根源；
• 少数 Type III 设备的 bootloader 会“通融”接受手动加入的 initramfs（如部分小米机型），而另一些则完全拒绝（如三星 S10 / Note 10），行为完全取决于 OEM 的 bootloader 实现，这也是文档强调“没有可靠探测手段，只能实测”的原因。

三、镜像 Patch 完整流程（核心章节）

完成“是否有 ramdisk”与“目标镜像文件”这两项准备后，进入安装主流程。文档给出的步骤如下，全部保留可复制命令：

1. 将 boot.img / init_boot.img / recovery.img 拷入设备；
2. 在 Magisk 应用的 Magisk 卡片中点击 Install（安装）；
3. 若 patch 的是 recovery 镜像，勾选 “Recovery Mode” 选项；
4. 安装方式选择 “Select and Patch a File”（选择并修补文件），选中目标镜像；
5. 开始安装后，用 ADB 把修补产物拷回电脑：

adb pull /sdcard/Download/magisk_patched_[random_strings].img

6. 将修补后的镜像刷回设备，多数设备进入 fastboot 模式后执行：

fastboot flash boot /path/to/magisk_patched_[random_strings].img
# 或
fastboot flash init_boot /path/to/magisk_patched_[random_strings].img
# 或
fastboot flash recovery /path/to/magisk_patched_[random_strings].img

7. （可选）如果设备有独立的 vbmeta 分区，需要同时关闭验证：

fastboot flash vbmeta --disable-verity --disable-verification vbmeta.img

注意：该操作可能导致数据被清空。 8. 重启并打开 Magisk 应用。若你清空过数据，看到的是一个 stub 版应用，用它引导（bootstrap）出完整版即可；随后会出现环境修复（environment fix）提示，点击并等待重启。完成。

警告（原文档强调）：绝对不要刷写他人分享的修补镜像，也不要拿镜像到另一台设备上 patch，哪怕机型完全相同！ 恢复手段可能是一次完整的数据清空。永远在你打算安装 Magisk 的那台设备上完成 patch。

源码视角：Patch 流程到底做了什么

在应用内点击“选择并修补文件”后，FlashViewModel.kt 会以 Const.Value.PATCH_FILE 分派到 MagiskInstaller.Patch。整个流程在 MagiskInstaller.kt 中实现，几个关键细节与文档命令一一对应：

• 输出文件名：destName（MagiskInstaller.kt）生成 magisk_patched-<版本码>_<5位随机串>，即文档中 magisk_patched_[random_strings].img 的真实来源（是否启用随机后缀由配置项 Config.randName 决定）。
• 输入文件类型自动识别：processFile() 读取文件头 512 字节做魔数判断——tar 格式（ustar 魔数，常见于三星 AP 包）会走 processTar() 逐条目处理；CrAU 魔数说明是 OTA payload，走 Payload 提取；PK\x03\x04 魔数说明是 zip 类容器（如 ROM 包），走 ExtractImage 提取内部镜像；其余视为裸镜像直接拷贝。
• tar 包内的 patch 优先级：processTar() 遵循 recovery > init_boot > boot 的优先级挑选目标镜像；若 tar 内含 vbmeta.img，会将其 flags 偏移 120 处写入值 3（即 HASHTREE_DISABLED | VERIFICATION_DISABLED），并据此关闭“boot 内嵌 vbmeta patch”（MagiskInstaller.kt）。
• 真正调用 patch 脚本：patchBoot()（MagiskInstaller.kt）通过环境变量注入全部安装选项后执行：

KEEPFORCEENCRYPT=${Config.keepEnc} \
KEEPVERITY=${Config.keepVerity} \
PATCHVBMETAFLAG=${Info.patchBootVbmeta} \
RECOVERYMODE=${Config.recovery} \
LEGACYSAR=${Info.legacySAR} \
sh boot_patch.sh $srcBoot

这些环境变量正是 scripts/boot_patch.sh 头部注释声明的配置项。boot_patch.sh 的执行过程可分为四段：

1. 解包：./magiskboot unpack <image>，并识别 ChromeOS / vendor boot 等特殊镜像；
2. ramdisk 检查与 patch：自动探测 ramdisk.cpio、vendor_ramdisk/init_boot.cpio、vendor_ramdisk/ramdisk.cpio 三种路径；若原镜像已是 Magisk patch 过的，会从 .backup/.magisk 还原 stock 状态；然后用 magiskboot cpio 把 magiskinit 替换进 init、注入 magisk.xz / stub.xz / init-ld.xz（均用 xz 压缩以节省 ramdisk 空间）、写入 config（记录 KEEPVERITY、RECOVERYMODE、PREINITDEVICE、SHA1 等），并备份原始 ramdisk 到 .backup/；
3. 二进制 patch：对 dtb/kernel_dtb/extra 修补 fstab；对 kernel 则包含若干针对三星的 hexpatch——移除 RKP、defex、PROCA，以及在 LEGACYSAR 设备上将内核字符串 skip_initramfs 改为 want_initramfs 强制加载 rootfs（scripts/boot_patch.sh）。这也解释了为何 patch 结果与具体设备强绑定、绝不能跨设备使用。
4. 重新打包：./magiskboot repack 生成 new-boot.img。

若走“直接安装”（应用内升级），则跳过手工刷写，由 flashBoot() 调用 scripts/app_functions.sh 中的 direct_install，直接 flash_image new-boot.img <boot分区>，并在分区空间不足或只读时给出明确报错；fix_env 随后把二进制拷贝到 /data/adb 并修正权限。

四、卸载 Magisk

文档给出的卸载方式有两种：

• 推荐：直接在 Magisk 应用内卸载。源码对应 MagiskInstaller.Uninstall，它执行 scripts/app_functions.sh 中的 run_uninstaller：把 APK 内的 assets/* 与 lib/* 解压到 /dev/tmp/install，然后以 INSTALLER 指向该目录运行 scripts/uninstaller.sh；成功后 3 秒内通过 pm uninstall 移除应用自身（MagiskInstaller.kt）。
• 自定义 recovery 场景：把 Magisk APK 重命名为 uninstall.zip，像普通 flashable zip 一样刷入即可。

五、Magisk in Recovery：无 Boot Ramdisk 设备的运行机制

对于 boot 分区不含 ramdisk 的设备，Magisk 只能“劫持” recovery 分区。代价是：每次想要 Magisk 生效，都必须重启进 recovery。

劫持之后，Magisk 保留了一个“真 recovery”逃生机制：每个机型有各自的进 recovery 按键组合（例如 Galaxy S10 为 电源 + Bixby + 音量上）。规则是——按下组合键、设备震动并出现开机画面时：

• 松开所有按键 → 进入带 Magisk 的系统；
• 长按音量上直到出现 recovery 界面 → 进入真正的 recovery 模式。

文档对“从关机状态开始”的三种路径做了总结表：

操作序列	结果
正常开机	无 Magisk 的系统
Recovery 组合键 → 开机画面 → 松开全部按键	带 Magisk 的系统
Recovery 组合键 → 开机画面 → 长按音量上	Recovery 模式

文档同时注明：这种情况下不能用自定义 recovery 来安装或升级 Magisk（自定义 recovery 的 zip 刷入通道无法触及被 Magisk 占据的 recovery 分区）。从源码看，check_boot_ramdisk 在判定为 legacy SAR 且非 A/B 时会自动置位 RECOVERYMODE=true（scripts/app_functions.sh），该标志随 config 写入 patch 后的 ramdisk，控制 Magisk 在 recovery 环境下的行为。

六、三星设备专属流程

三星设备在安装前必须接受两个不可逆事实：

• 安装 Magisk 会触发 Knox 保修位，不可逆；
• 首次安装要求完整数据清空（这还不包括解锁 bootloader 时那次清空），务必提前备份。

6.1 刷机工具

工具	平台
Samsung Odin3	仅 Windows（需搭配三星 USB 驱动）
Samsung Odin4	仅 Linux
Heimdall（或其社区 fork）	Windows / Linux / macOS 均可

以上工具的官方下载渠道参见原文档 docs/install.md 中的“Flashing Tools”小节（本文为避免外站链接不重复列出）。

6.2 前提检查：OEM Lock 与 KnoxGuard (RMM)

路径：设置 → 设备保养 → 维护模式 开启后，用按键组合进入 Download 模式查看状态。

OEM Lock 可能取值：

• ON (L)：完全锁定；
• ON (U)：bootloader 锁定，但允许 OEM 解锁；
• OFF (U)：完全解锁。

若 Download 模式不显示 OEM Lock 值，通常说明该设备因市场限制（美版/加版）不可解锁。

KnoxGuard 可能取值：

• Active、Locked：设备被运营商或保险公司远程锁定；
• Prenormal：临时锁定，达到 168 小时正常运行时长按理应自动解锁；
• Checking、Completed、Broken：设备处于解锁状态。

只要 KnoxGuard 处于 Active，无论 bootloader 是否解锁，都无法安装/运行 Magisk。

6.3 解锁 Bootloader

1. 在 开发者选项 → OEM 解锁 中允许解锁；
2. 关机后用机型对应的按键组合进入 Download 模式；
3. 长按音量上确认解锁。这会清空数据并自动重启；
4. 走完初始设置。设置期间保持联网；
5. 开启开发者选项，确认 OEM 解锁选项存在且呈灰色不可点状态——这说明 KnoxGuard 尚未锁定设备；
6. 此时 bootloader 接受 download 模式下的非官方镜像。

6.4 安装步骤（AP tar 包 Patch）

1. 从三星官方服务器下载对应机型最新固件（可用 SamFirm 系工具、Frija、Samloader、Bifrost 等固件下载工具，具体见 docs/install.md）；
2. 解压固件，把 AP 文件（通常命名 AP_[机型_软件版本].tar.md5）拷入设备；
3. 点击 Magisk 应用中的 Install；
4. 若设备无 boot ramdisk，勾选 “Recovery Mode”；
5. 方式选择 “Select and Patch a File”，选中 AP tar 文件；
6. 安装完成后用 ADB 拉取修补产物（不要用 MTP，大文件传输已知会损坏）：

adb pull /sdcard/Download/magisk_patched_[random_strings].tar

7. 重启进 Download 模式，用 Odin 将 magisk_patched.tar 作为 AP 刷入，同时刷原始固件的 BL、CP 和 CSC（不是 HOME_CSC，因为首次安装要清空数据）；
8. Odin 完成后设备自动重启，如提示请选择执行出厂重置；
9. 若设备无 boot ramdisk，现在重启进 recovery 以激活 Magisk（原理见上文“Magisk in Recovery”）；
10. 安装并打开 Magisk 应用，它会提示追加环境设置，让应用完成工作并自动重启。完成。

从源码看，这一步对应 MagiskInstaller.Patch 处理 tar 输入的分支：processTar() 会在 AP 包内定位 boot.img/init_boot.img/recovery.img 条目并逐一修补（三星 AP 包中 boot 镜像常以 .lz4 压缩存放，代码中 FramedLZ4CompressorInputStream 分支即为此处理），其余条目原样透传写回新 tar，最终输出 magisk_patched-<code>_<随机串>.tar（MagiskInstaller.kt）。

6.5 系统升级（OTA）

一旦三星设备 root 成功，将不能再通过 OTA 升级系统。手动升级流程与上述 AP patch 流程完全一致，唯一区别在 Odin 刷写步骤：升级场景下 不要使用 CSC，改用 HOME_CSC（保留用户数据，因为这是升级而非首装）。

6.6 重要注意事项

• 永远不要把 boot、init_boot、recovery 或 vbmeta 分区恢复为 stock 版本——会直接变砖，唯一救砖手段是 Odin 完整恢复 + 数据清空；
• 升级固件时永远不要直接使用 stock 的 AP tar 包，必须先经 Magisk 应用 patch 再刷入。

七、Custom Recovery 方式（已弃用，仅作历史参考）

原文档声明：此方式已弃用，仅以最低限度维护。出现问题请改用“镜像 Patch”方式。

仅当设备 boot 分区有 ramdisk 时才可行，步骤：

1. 下载 Magisk APK；
2. 把 .apk 扩展名改为 .zip（例如 Magisk-v24.0.apk → Magisk-v24.0.zip；Windows 上若无法改名，可用 Android 文件管理器或 recovery 自带工具改名）；
3. 像普通 flashable zip 一样刷入；
4. 重启后检查 Magisk 应用是否已安装，没有则手动安装 APK；
5. 打开应用，它会提示重新安装——在应用内直接完成重装并重启。若使用 MTK 设备（开机后锁定 boot 分区），需另行 patch boot 镜像并通过 custom recovery 或 fastboot 刷入。

警告：模块的 sepolicy.rule 可能存放在 cache 分区，不要清空 CACHE 分区。

八、小结与排障要点

• 安装前先用应用首页的 Ramdisk 字段确定目标镜像（有 → boot.img/init_boot.img，无 → recovery.img 并接受每次重启进 recovery 的代价）；
• patch 与安装必须发生在同一台设备上，这是全部警告中优先级最高的一条；
• 有独立 vbmeta 分区时记得 fastboot flash vbmeta --disable-verity --disable-verification；
• 三星设备额外注意 Knox/RMM 状态、CSC 与 HOME_CSC 的选择、以及“恢复 stock boot 镜像即变砖”的红线；
• 已装 Magisk 的机器升级时，优先使用应用内 Direct Install（对应 MagiskInstaller.kt 的 Direct 流程），比手工 patch 安全且省事。

涉及本节的仓库文件：docs/install.md（本文主体）、docs/boot.md（启动方式与设备类型背景）、scripts/boot_patch.sh（镜像 patch 脚本）、scripts/app_functions.sh（应用内置 shell 函数）、app/core/src/main/java/com/topjohnwu/magisk/core/tasks/MagiskInstaller.kt（应用内安装任务实现）、app/apk/src/main/java/com/topjohnwu/magisk/ui/flash/FlashViewModel.kt（安装界面分派逻辑）。