Walle payload_writer 深度指南:向 APK Signing Block 写入渠道与自定义信息
Walle payload_writer 深度指南:向 APK Signing Block 写入渠道与自定义信息
Walle(瓦力)是美团开源的 Android Signature V2 Scheme 签名下的新一代渠道包打包工具,其核心思路是在 APK 的 APK Signature Block 区块中追加自定义的 ID-value 信息,从而无需重新打包、无需重新签名即可生成渠道包。本篇文章聚焦 Walle 生态中的写入端模块 payload_writer,详细讲解其两个对外写入类 ChannelWriter 与 PayloadWriter 的依赖引入、API 用法、覆盖规则、底层写入原理以及与命令行工具、读取端模块的协作方式。读完本文,你将掌握如何脱离 Gradle 插件与 CLI,直接在 Java 代码层面向任意 V2 签名 APK 写入/移除渠道及自定义信息,并理解其实现细节与边界约束。
一、模块定位与依赖引入
payload_writer 是 Walle 对 APK Signing Block 区块进行写入操作的独立封装模块,与读取端模块 payload_reader 成对出现(读取端说明见 payload_reader/README.md)。它不依赖 Gradle 插件环境,可在独立的 Java 工程中使用,适合需要深度定制渠道写入流程的场景。
在 build.gradle 中引入依赖:
dependencies {
compile 'com.meituan.android.walle:payload_writer:1.1.7'
}
模块对外暴露两个写入类(对应源码位于 payload_writer/src/main/java/com/meituan/android/walle/):
- ChannelWriter:向 Walle 内置 id 对应的区域写入/移除信息,一般存放渠道和额外信息。额外信息 key 相同时覆盖写入。
- PayloadWriter:自定义 id 写入,id 相同时覆盖。
关于 org.json 依赖的特别说明
payload_writer 的 ChannelWriter 内部依赖 org.json.JSONObject 来序列化渠道与额外信息。在 Android 系统中可以直接复用系统自带的 org.json(无需额外引入,可减少方法数),但如果要在非 Android 系统(如普通 JVM、服务器端)使用此 jar 包,需要手动添加依赖:
compile 'org.json:json:20080701'
二、ChannelWriter:向 Walle 内置 id 写入渠道与额外信息
ChannelWriter 是绝大多数场景下应该优先使用的写入入口。它把所有数据序列化成一个 JSON 字符串,写入 Walle 约定的内置区块 id(APK_CHANNEL_BLOCK_ID,即 0x71777777,定义见 ApkUtil.java)。
1. 基础 API 一览
ChannelWriter 的全部公开静态方法(源码见 ChannelWriter.java):
| 方法签名 | 说明 |
|---|---|
put(File apkFile, String channel) |
仅写入渠道号 |
put(File apkFile, String channel, boolean lowMemory) |
写入渠道号,可开启低内存模式 |
put(File apkFile, String channel, Map<String, String> extraInfo) |
同时写入渠道号与额外信息 |
put(File apkFile, String channel, Map<String, String> extraInfo, boolean lowMemory) |
同时写入渠道号与额外信息,可开启低内存模式 |
putRaw(File apkFile, String string) |
直接写入原始字符串(覆盖整块内容) |
putRaw(File apkFile, String string, boolean lowMemory) |
直接写入原始字符串,可开启低内存模式 |
remove(File apkFile) |
移除 Walle 内置 id 对应的整块内容 |
remove(File apkFile, boolean lowMemory) |
移除内容,可开启低内存模式 |
其中 channel 参数可传 null(此时只写额外信息、不写渠道),extraInfo 也可传 null。
2. 写入与覆盖规则(源码级解析)
put 系列方法的核心逻辑在 ChannelWriter.java 的 put(apkFile, channel, extraInfo, lowMemory) 中:
- 先通过
ChannelReader.getMap(apkFile)读出 APK 中已存在的渠道信息(若 APK 此前已写入过渠道),合并进newData; - 合并本次传入的
extraInfo,并强制移除其中以channel为 key 的项(extraInfo.remove(ChannelReader.CHANNEL_KEY)),防止额外信息污染渠道字段; - 若
channel非空,则写入newData.put(ChannelReader.CHANNEL_KEY, channel),其中CHANNEL_KEY的值为字符串"channel"(见 ChannelReader.java); - 将合并后的
Map通过new JSONObject(newData).toString()序列化为 JSON 字符串; - 调用
putRaw(apkFile, jsonObject.toString(), lowMemory)真正落盘。
从该逻辑可以推断出两个关键行为:
- 额外信息 key 相同时覆盖写入:由于
Map.putAll的语义,后传入的extraInfo会覆盖 APK 中已存在的同名 key; - channel 与 extraInfo 合并共存:渠道号被统一存为 JSON 中的
"channel"key,因此额外信息中不应再出现以channel为 key 的项,这正是源码中强制remove该 key 的原因。
读取端对应解析:ChannelReader.get(apkFile) 会把 JSON 中 "channel" 对应的值取出来作为渠道号,其余 key-value 作为额外信息返回(见 ChannelReader.java 与 ChannelInfo.java)。
3. putRaw:写入原始内容
putRaw 不做任何 JSON 组装,直接把字符串以 UTF-8 字节写入内置 id 区域(ChannelWriter.java):
public static void putRaw(final File apkFile, final String string, final boolean lowMemory) throws IOException, SignatureNotFoundException {
PayloadWriter.put(apkFile, ApkUtil.APK_CHANNEL_BLOCK_ID, string, lowMemory);
}
⚠️ 注意:使用 putRaw 写入的原始内容若不符合 ChannelReader 期望的 JSON 格式,将导致后续 ChannelReader.get/getMap 解析失败(getMap 内部捕获 JSONException 后返回 null)。除非你完全清楚自己在做什么,否则建议使用 put 系列方法。
4. remove:移除渠道信息
ChannelWriter.remove(apkFile);
移除后该 APK 中不再存在 Walle 内置 id 对应的数据块,读取端 ChannelReader 将返回 null/空结果。
三、PayloadWriter:自定义 id 写入
PayloadWriter 是更底层的写入入口,允许向 APK Signing Block 中任意自定义 id 写入内容,不局限于渠道。公开方法(源码见 PayloadWriter.java):
| 方法签名 | 说明 |
|---|---|
put(File apkFile, int id, String string) |
按 id 写入字符串(UTF-8) |
put(File apkFile, int id, ByteBuffer buffer) |
按 id 写入字节缓冲(需 LITTLE_ENDIAN 字节序) |
putAll(File apkFile, Map<Integer, ByteBuffer> idValues) |
批量写入多个 id-value 对,id 相同时覆盖 |
remove(File apkFile, int id) |
按 id 移除内容 |
所有重载均提供带 boolean lowMemory 参数的版本。
1. id 相同则覆盖
putAll 的实现(PayloadWriter.java)先把原始区块中已有的所有 id-value 解析出来,再执行 originIdValues.putAll(idValues),因此已存在的 id 会被新值覆盖,其余 id 原样保留。
2. 关键约束:请确保 Android 未使用此 id
这是 payload_writer README 中反复强调的注意点。APK Signing Block 中的 ID-value 对并非自由空间,Android 官方已占用若干 id,例如:
| id | 用途 |
|---|---|
0x7109871a |
APK Signature Scheme v2 签名块(APK_SIGNATURE_SCHEME_V2_BLOCK_ID) |
0x42726577 |
V3 方案引入的 VERITY padding 块(VERITY_PADDING_BLOCK_ID) |
0x71777777 |
Walle 内置渠道块(APK_CHANNEL_BLOCK_ID) |
以上常量均定义于 ApkUtil.java。若自定义写入的 id 与 Android 签名/校验机制使用的 id 冲突,可能破坏 APK 签名校验或系统安装流程。源码中的注释也明确要求使用未被占用的未知 ID(参见 PayloadWriter.java 的 javadoc)。
同时,PayloadWriter 写入的内容如果覆盖了 v2 签名块所在 id,handleApkSigningBlock 内部会检测不到 v2 签名块并抛出 IOException("No APK Signature Scheme v2 block in APK Signing Block")(见 PayloadWriter.java)。
四、底层原理:APK Signing Block 的读写流程
要理解 payload_writer 为何能"不动签名、不重打包"地改 APK,需要了解其底层的文件操作流程。所有写入最终都会汇聚到 PayloadWriter.handleApkSigningBlock(PayloadWriter.java),其核心步骤如下:
- 定位 ZIP EOCD 与 Central Directory:通过
ApkUtil.getCommentLength从文件尾部回溯定位 ZIP 的 End of Central Directory(EOCD),再读取其中的 Central Directory 起始偏移(见 ApkUtil.java); - 定位 APK Signing Block:APK Signing Block 紧邻 Central Directory 之前,通过其尾部 magic(
"APK Sig Block 42")与 size 字段确定区块位置(ApkUtil.findApkSigningBlock,见 ApkUtil.java); - 解析现有 ID-value 对:将区块内所有 ID-value 对解析成
Map<Integer, ByteBuffer>(ApkUtil.findIdValues); - 校验 v2 签名块存在:若找不到
0x7109871a对应的 v2 签名块,说明该 APK 未经 V2 签名,直接抛异常拒绝写入; - 执行写/改/删处理器:由
ChannelWriter/PayloadWriter传入的ApkSigningBlockHandler决定如何合并、覆盖或剔除 ID-value 对,最终构造出新的ApkSigningBlock; - 写回文件:在原 APK 上以
RandomAccessFile定位到 APK Signing Block 起始位置,写入新的区块内容,随后重写 Central Directory 并修正 EOCD 中的 Central Directory 偏移量(见 PayloadWriter.java)。
APK Signing Block 的字节格式
ApkSigningBlock(ApkSigningBlock.java)严格遵循 Android 官方的 v2 签名方案格式(所有数字字段为小端序):
uint64: block size in bytes (excluding this field)
repeat: uint64-length-prefixed ID-value pairs
├─ uint32: ID
└─ (len - 4) bytes: value
uint64: block size(与首字段相同)
uint128: magic "APK Sig Block 42"
单个 ID-value 对的大小由 ApkSigningPayload 计算:8 + 4 + value.length(size + id + value,见 ApkSigningPayload.java)。整个区块的写入由 ApkSigningBlock.writeApkSigningBlock 完成,会依次输出 size、每对的 length+ID+value、尾部 size 与 magic。
lowMemory 低内存模式
写入超大 APK 时,普通模式会把整个 Central Directory 一次性读入内存(new byte<a href="https://link.gitcode.com/i/0647c61c4db30410fc782ae8522bdaa5" target="_blank">(int)(fileChannel.size() - centralDirStartOffset)])。开启 lowMemory = true 后,改为将 Central Directory 先流式写入同目录下的临时文件,再在写回时以 1KB 缓冲流式拷贝(见 [PayloadWriter.java),以略微降低速度换取内存占用的大幅下降。对内存受限的服务器环境,建议开启。
关于 VERITY padding 的处理
当原 APK 的 Signing Block 中存在 V3 方案引入的 VERITY_PADDING_BLOCK_ID(0x42726577)时,写入逻辑会先移除旧的 padding 块,按 4096 字节(ANDROID_COMMON_PAGE_ALIGNMENT_BYTES)页对齐重新计算并补回新的 padding 块,以维持文件的对齐约束(见 PayloadWriter.java)。
五、与命令行工具及读取模块的协作
payload_writer 并非孤立模块,它是 Walle 命令行工具 walle-cli 的写入引擎:
walle-cli的put命令直接调用ChannelWriter.put(outputFile, channel, extraInfo)(见 PutCommand.java);batch命令逐个渠道调用ChannelWriter.put(见 BatchCommand.java),其中渠道文件支持#注释(示例见 app/channel);batch2命令解析 JSON 配置文件(含defaultExtraInfo、defaultExtraInfoStrategy、excludeDefaultExtraInfo、alias等字段,示例见 app/config.json),再调用ChannelWriter.put(channelApk, channel, extraInfo)批量产出(见 Batch2Command.java);remove命令逐个文件调用ChannelWriter.remove(file)(见 RemoveCommand.java)。
读取侧由 payload_reader 模块承接:ChannelReader/PayloadReader 以同样方式定位 APK Signing Block 并解析 ID-value 对(见 PayloadReader.java),与写入端形成闭环。完整 CLI 用法可参考 walle-cli/README.md。
六、使用建议与注意事项
- APK 必须经过 V2 签名:写入过程强依赖 APK Signing Block 中的 v2 签名块存在,未用 V2 方案签名的 APK 无法使用本模块;同时,使用 apksigner 重新对 APK 签名会导致已写入的渠道信息丢失,需要再次写入渠道信息。
- 不要动系统保留 id:自定义 id 请避开
0x7109871a、0x42726577等官方占用 id;额外信息中不要出现以channel为 key 的项。 - 非 Android 环境需补 org.json 依赖:
compile 'org.json:json:20080701';Android 环境直接复用系统自带实现。 - 大文件优先 lowMemory:内存敏感场景请使用带
lowMemory参数的重载。 - 读写配对使用:写入时注意与读取端
ChannelReader/PayloadReader的解析格式保持一致,避免写入非 JSON 原始内容导致读取端解析失败。
从依赖引入、两个写入类的 API 与覆盖规则,到 APK Signing Block 的字节级操作原理,再到与 walle-cli 的协作方式,payload_writer 为开发者提供了一条不经过重新打包即可向 V2 签名 APK 写入渠道与自定义信息的完整通路。结合 payload_writer/README.md、payload_writer/src/main/java/com/meituan/android/walle/ChannelWriter.java 与 PayloadWriter.java 深入阅读源码,可以进一步理解每一步的实现细节。