1. 手动打包的 system.img 总和官方对不上:问题出在工具链编排层
做系统镜像替换的人多半遇到过:自己用 make_ext4fs 打包出来的 system.img,刷进去能开机,但一比对 md5 就和官方编译产物对不上,OTA 校验直接红。这不是命令敲错了,而是漏掉了构建体系里那层编排逻辑。这套代码开发工具链由 mkuserimg.sh、make_ext4fs、img2simg、simg2img 四个角色组成:一个负责按官方参数编排,一个负责把目录做成 ext4,两个负责 raw 与 sparse 之间来回转换。搞不清谁调谁,就会在“看起来能跑”和“完全一致”之间反复翻车。下面按实际操作顺序拆开讲。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链的四件套分工:谁在调谁,谁只做转换
2.1 mkuserimg.sh 是编排层,不是独立二进制
很多人第一次找 mkuserimg.sh,会习惯性地 which mkuserimg.sh,结果什么都看不到,于是以为环境没装好。其实它位于 build/tools/releasetools/ 下,是一个 shell 脚本,用文本编辑器就能打开。它的价值不在算法,而在把官方构建体系那套硬编码参数固定下来:块大小、inode 大小、校验开关、稀疏格式转换,全部按固定顺序串起来。你手写 make_ext4fs 时少写一个 --sha1,产出的镜像就可能和官方差一个校验段。
典型调用方式如下,参数顺序不要随意调换:
bash复制# 在构建环境的 releasetools 目录下执行
# -s:强制输出 sparse image,内部会自动调用 img2simg
# system_dir/:待打包的根目录
# system.img:输出文件名
# ext4:文件系统类型
# /system:挂载点
# 2048M:逻辑大小,按分区表给,不是目录实际占用
./mkuserimg.sh -s system_dir/ system.img ext4 /system 2048M
这一行命令把普通目录变成可刷写的稀疏镜像。-s 不是可有可无的装饰,官方产物默认就是 sparse;去掉它,部分刷机工具会直接不认。最后一个 2048M 是逻辑大小,给的是分区容量上限,和目录里实际放了多少文件没有关系。脚本内部还会追加 --junk-paths、--sha1,较新版本构建里还会带 -c 压缩开关,这些都不是手写命令时能轻易记全的。
2.2 make_ext4fs 负责做文件系统,img2simg 负责换外套
make_ext4fs 的职责很单一:把一个目录写成 ext4 格式的 raw 镜像。它关心的是块分配、inode 表、目录项这些文件系统内部结构。img2simg 不碰文件系统内容,只把 raw 镜像里连续的全零块压掉,生成 sparse image。sparse 的本质是一张块表:哪些块有数据、哪些块是空的,空块不占实际存储,所以同样内容下 sparse 体积明显小于 raw。simg2img 则反过来,把 sparse 的块表展开,还原成可以直接挂载或喂给只认 raw 的工具的镜像。
四件套的输入输出关系可以用一张表固定下来:
| 工具 | 输入 | 输出 | 职责 |
|---|---|---|---|
| mkuserimg.sh | 目录 + 参数 | sparse 镜像 | 编排参数、追加校验、调用下层工具 |
| make_ext4fs | 目录 | ext4 raw 镜像 | 生成文件系统结构 |
| img2simg | raw 镜像 | sparse 镜像 | 把全零块压成块表 |
| simg2img | sparse 镜像 | raw 镜像 | 展开块表,还原连续镜像 |
这张表决定了排查问题的下探深度。镜像内容不对,先看目录;镜像体积不对,先看 sparse 转换;镜像和官方 md5 对不上,先看 mkuserimg.sh 有没有被绕过。层级搞反了,就会在 make_ext4fs 的参数里反复试错,却始终碰不到真正的原因。
2.3 调用关系决定了你该在哪一层动手
日常改分区内容,只需要动最上层的 mkuserimg.sh。它是官方构建体系实际调用的入口,参数组合经过验证,产出和源码编译结果最容易对齐。只有两类情况需要下探:一是镜像体积异常,需要确认 img2simg 有没有正确压掉空块;二是挂载失败,需要确认 make_ext4fs 生成的文件系统结构有没有被破坏。直接手写 make_ext4fs 看起来更“底层”,实际上绕过了 --junk-paths 和 --sha1 这些开关,产出和官方不一致几乎是必然的。
我见过一种常见误用:有人为了“控制体积”,在 make_ext4fs 上手动改块大小,结果文件系统布局变了,刷机后分区能挂载但读写性能异常,查了两天才回到 mkuserimg.sh 的默认参数。块大小和 inode 大小不是不能改,而是改了之后要和分区表、内核挂载参数一起对,单改打包端没有意义。
3. 从目录到可刷写镜像:四件套的完整操作顺序
3.1 准备输入目录:权限、隐藏文件与挂载点
打包前的目录准备比打包命令本身更容易出问题。输入目录里混进版本控制目录、临时文件、权限错乱的条目,都会被原样写进镜像。刷机后多出几个不该存在的文件,或者某些系统文件权限不对,表现就是开机后某个服务起不来,日志里还看不出明显报错。
我一般按下面几步把目录清干净再打包:
bash复制# 1. 建立干净的输入目录
mkdir -p system_dir
# 2. 放入待打包内容,-a 保留权限和时间戳
cp -a unpacked_system/. system_dir/
# 3. 清掉版本控制目录和临时文件,避免被一起打进镜像
find system_dir -name ".git" -type d -prune -exec rm -rf {} +
find system_dir -name "*.tmp" -type f -delete
# 4. 统一权限,避免 uid/gid 与官方产物偏差过大
chmod -R u+rwX,go+rX system_dir
cp -a 的作用是保留原目录的权限位和时间戳,直接用 cp -r 会把权限压成当前用户的默认值,打包后文件属性全变。find 两条命令分别清目录和清文件,.git 这种目录如果留在里面,镜像体积会莫名其妙涨一截。chmod 只做最小收敛,让目录可读、文件可读,不追求和官方完全一致的 uid/gid,因为那需要额外的 ownership 映射,普通替换场景用不到。
挂载点参数要和分区表对上。上面命令里的 /system 是挂载点,不是输入目录名,写错了镜像内部路径结构会偏。逻辑大小 2048M 也要按目标分区来,不要看目录实际大小反推。
3.2 用 mkuserimg.sh 生成 sparse 镜像
目录准备好之后,生成镜像只需要一条命令:
bash复制# 生成 sparse 格式的 system.img
# -s 必须保留,官方产物默认是稀疏镜像
./mkuserimg.sh -s system_dir/ system.img ext4 /system 2048M
这条命令背后实际发生的事比表面多:脚本先检查 make_ext4fs 和 simg2img 是否在 $PATH 里,然后按固定参数调用 make_ext4fs 生成 raw 镜像,再调用 img2simg 转成 sparse,最后写入 SHA1 校验值。你看到的 system.img 已经是稀疏格式,不是 raw。很多人拿这个文件去 mount -o loop,挂载失败,就是因为把 sparse 当成了 raw。
参数里最容易被忽略的是最后一个逻辑大小。给 2048M 表示这个分区逻辑容量是 2GB,目录内容不能超过它。给小了,脚本执行中途会报空间不足;给大了,镜像不会自动扩容分区,刷进去还是按分区表来。按板级分区表填,不要凭感觉。
3.3 反向验证:simg2img 还原,img2simg 再压缩
生成完不要急着刷,先做一次往返转换,确认 sparse 和 raw 之间没有丢内容:
bash复制# 把 sparse 镜像还原成 raw,便于挂载检查或给只认 raw 的工具使用
simg2img system.img system_raw.img
# 查看 raw 镜像的文件系统标识,确认是 ext4
file system_raw.img
# 再把 raw 压回 sparse,验证转换链路可逆
img2simg system_raw.img system_repacked.img
# 比对两次 sparse 的 md5,确认转换没有引入差异
md5sum system.img system_repacked.img
simg2img 的输入是 sparse、输出是 raw;img2simg 的输入是 raw、输出是 sparse。两个命令都是“源在前、目标在后”,写反了会得到一个空文件或者直接报错。file 命令用来确认 raw 镜像的文件系统标识,正常会显示 ext4 相关信息。最后一步 md5 比对是关键:如果两次 sparse 的 md5 一致,说明转换链路稳定;不一致就要查 img2simg 的版本或者输入 raw 有没有被截断。
这里有一个边界:往返转换一致,不代表和官方镜像一致。官方镜像的 md5 取决于 mkuserimg.sh 追加的那些开关,往返验证只能证明你自己的转换没丢东西。
3.4 挂载检查与内容抽查
需要确认镜像里文件是否完整时,我一般会把 raw 镜像挂到临时目录看一眼:
bash复制# 需要 loop 设备权限,普通用户可能被拒绝
mkdir -p mnt
mount -o loop system_raw.img mnt
# 抽查关键目录和文件权限
ls -l mnt/
ls -l mnt/bin/ | head
# 检查完卸载
umount mnt
mount -o loop 需要 root 或相应的 loop 设备权限,权限不够时会提示 permission denied,这不是镜像坏了。挂载后重点看两处:顶层目录结构是否和预期一致,关键可执行文件的权限位有没有被 chmod 改坏。检查完记得 umount,否则下次挂载会提示设备忙。
4. 代码开发工具的打包参数:block size、inode 与校验开关怎么定
4.1 -b 4096 与 -i 256:两个不要随手改的硬编码
mkuserimg.sh 默认使用 -b 4096 作为块大小、-i 256 作为 inode 大小。这两个值不是随便定的,它们决定了 ext4 文件系统的内部布局。块大小影响大文件读写效率,inode 大小影响能容纳的扩展属性和时间戳精度。手动打包时如果把块大小改成 2048 或 8192,文件系统结构就变了,产出的镜像 md5 必然和官方不同,严重时刷机后内核挂载参数对不上,分区直接挂载失败。
除非明确知道目标分区和内核要求非默认值,否则这两个参数保持 mkuserimg.sh 的默认。想改之前先问一句:改了之后,分区表、内核 cmdline、OTA 校验脚本能不能一起改?只改打包端,等于给自己埋雷。
4.2 --junk-paths、--sha1、-c:三个强制开关各自管什么
mkuserimg.sh 相比手写 make_ext4fs,多出来的主要是这三个开关:
| 开关 | 作用 | 不加的后果 |
|---|---|---|
--junk-paths |
过滤输入路径里的异常字符,避免路径问题影响打包结果 | 目录里带特殊字符的路径可能让产出和官方不一致 |
--sha1 |
计算并写入 SHA1 校验值 | OTA 校验或镜像完整性检查会失败 |
-c |
启用 ext4 压缩,仅较新构建版本支持 | 老版本加上会报参数错误;新版本不加则体积偏大 |
--junk-paths 解决的是路径层面的干扰。输入目录里如果有空格、特殊符号或者构建过程留下的临时路径,不过滤的话,打包结果可能和官方产物在目录项层面产生差异。--sha1 是 OTA 校验直接依赖的字段,手动打包最容易漏的就是它。-c 要看构建版本,较新的构建体系才支持,老版本脚本不认这个参数,加上直接报错。三个开关里,前两个建议无脑保留,-c 先确认版本再决定。
4.3 逻辑大小 2048M 与分区表的对应关系
最后一个参数 2048M 是逻辑大小,不是实际占用,也不是压缩后大小。它对应分区表里这个分区的容量上限。目录内容 800M,你给 2048M,镜像逻辑大小还是 2048M,空的部分在 sparse 里被压掉,实际文件可能只有几百兆。反过来,目录内容 2.2G,你给 2048M,脚本执行到一半就会失败。
判断逻辑大小的方法只有一个:看目标设备的分区表,不要看目录 du 出来的数字。不同板级的分区布局不一样,同一个目录换一块板子,逻辑大小可能就要调。给足之后,sparse 转换会负责把空块压掉,不需要为了省体积把逻辑大小卡得很紧。
4.4 参数对齐之后,为什么还要走 mkuserimg.sh
有人会问:参数我都知道了,直接手写 make_ext4fs 加 img2simg 不行吗?行,但成本高。mkuserimg.sh 里的参数顺序、默认值、开关组合是官方构建体系验证过的,手写要完全复现,得把脚本逐行读一遍,还要保证工具版本一致。更现实的问题是,脚本会做前置检查,比如依赖是否在 $PATH、输入目录是否存在,手写命令这些检查全没了,出错时连提示都没有。
我一般把 mkuserimg.sh 当成唯一入口,需要调整时改输入目录或逻辑大小,不动下层工具的参数。这样产出的镜像和官方构建体系走的是同一条路径,md5 对不上的概率最低。
5. 避坑与排查:五类翻车现场的现象、原因和解决
5.1 执行 mkuserimg.sh 报 command not found
现象:脚本刚跑起来就退出,提示 make_ext4fs: command not found 或 simg2img: command not found。
原因:mkuserimg.sh 依赖 make_ext4fs 和 simg2img 在 $PATH 中可用,而这两个工具不是系统自带,构建环境没编译或没导出路径时就会找不到。
解决:先确认依赖是否存在,缺失时编译 system/extras/ext4_utils/ 模块,或从预编译工具集中提取对应二进制,再把目录加入 $PATH。
bash复制# 确认两个依赖是否可见
which make_ext4fs
which simg2img
# 缺失时,把预编译工具目录加入 PATH,路径按实际改
export PATH=$PATH:/path/to/ext4_utils/bin
5.2 镜像能刷,但 md5 和官方对不上
现象:手动用 make_ext4fs 打包出来的镜像能开机,一比对 md5 就和官方产物不一致,OTA 校验失败。
原因:漏掉了 mkuserimg.sh 追加的 --junk-paths、--sha1,或者改过 -b 4096、-i 256 这两个硬编码参数。校验段和文件系统布局任何一处不同,md5 都会变。
解决:不要手写 make_ext4fs 拼参数,统一走 mkuserimg.sh。比对时使用和官方构建相同版本的脚本与工具,版本不一致时先对齐工具再谈 md5。
5.3 sparse 和 raw 混用,刷机工具报错
现象:刷机工具提示镜像格式不支持,或者写入后分区无法挂载,日志里出现块设备读取错误。
原因:mkuserimg.sh 默认产出的是 sparse 镜像,而部分刷机工具或挂载命令只接受 raw。把 sparse 当 raw 直接写入,块表被当成文件系统数据,必然出错。
解决:用 simg2img 把 sparse 还原成 raw 再喂给只认 raw 的工具;需要回写 sparse 时再用 img2simg 转回去。转换前先用 file 确认当前镜像格式。
5.4 输入目录混入隐藏文件,镜像体积莫名变大
现象:打包出来的镜像比预期大,挂载后发现顶层多出 .git 目录或一批 .tmp 文件。
原因:输入目录没有清理,打包工具会把目录下所有条目原样写进镜像。版本控制目录和临时文件不会自动被忽略。
解决:打包前用 find 清掉 .git 和临时文件,保留 --junk-paths 开关处理异常路径。目录准备步骤里加一条清理命令,比事后从镜像里删文件省事得多。
5.5 逻辑大小给小了,打包中途失败或镜像截断
现象:mkuserimg.sh 执行到一半报空间不足,或者输出镜像比输入目录实际内容还小,挂载后文件不全。
原因:最后一个参数是逻辑大小,表示分区容量上限,不是实际占用。给的值小于目录内容总量时,文件系统写不下。
解决:按目标设备分区表给足逻辑大小,比如 2048M。不要用 du 出来的目录大小反推,目录大小和分区容量是两回事。给大之后 sparse 会压掉空块,不会让最终文件同比例膨胀。
6. 把打包流程固化成脚本:校验、比对与归档的具体做法
手工敲命令迟早会漏参数,我后来把整个流程收进一个 bash 脚本,输入目录和逻辑大小作为参数,输出 sparse、raw 两份镜像和对应的校验文件。这样每次打包的动作一致,出问题时也有归档可查。
bash复制#!/usr/bin/env bash
set -euo pipefail
SRC_DIR="${1:?请输入待打包目录}"
OUT_DIR="${2:?请输入输出目录}"
LOGIC_SIZE="${3:-2048M}"
mkdir -p "$OUT_DIR"
# 1. 走官方编排层,生成 sparse 镜像
./mkuserimg.sh -s "$SRC_DIR" "$OUT_DIR/system.img" ext4 /system "$LOGIC_SIZE"
# 2. 同时保留一份 raw,便于挂载检查和给只认 raw 的工具
simg2img "$OUT_DIR/system.img" "$OUT_DIR/system_raw.img"
# 3. 记录校验值,和官方产物比对
md5sum "$OUT_DIR/system.img" | tee "$OUT_DIR/system.img.md5"
md5sum "$OUT_DIR/system_raw.img" | tee "$OUT_DIR/system_raw.img.md5"
# 4. 归档本次参数,出问题时能复现
printf 'src=%s\nlogic_size=%s\n' "$SRC_DIR" "$LOGIC_SIZE" > "$OUT_DIR/build.args"
set -euo pipefail 让脚本在任何一步失败时立即退出,避免带着半成品继续往下跑。SRC_DIR 和 OUT_DIR 是必填参数,缺了直接报错,防止空路径把当前目录打进去。LOGIC_SIZE 给了默认值 2048M,实际使用时按分区表覆盖。脚本保留 raw 副本是有意为之:排查挂载问题时 raw 比 sparse 好用,而 sparse 是刷机和分发的最终形态,两份都留着,来回转换的步骤就省了。
拿到官方镜像后,我一般先 md5sum 比对,不一致时按这个顺序查:先看 build.args 里的逻辑大小和官方是否一致,再挂载 raw 看目录内容有没有多出或少掉文件,最后才怀疑工具版本。这个顺序能把大部分问题挡在前两步,不用一上来就重新编译工具链。
从那以后我每次打包 system.img 都强制走 mkuserimg.sh,并且把 raw 和 sparse 各留一份、参数和 md5 一起归档。看起来多了一步,但下次再遇到“镜像能刷、校验不过”的情况,翻出上次的归档十分钟就能定位,比从头分析一遍省太多。希望帮到你。
