Walle payload_writer 深度指南:向 APK Signing Block 写入渠道与自定义信息

原创2026-10-14 22:37:361,379 阅读
文章标签:移动开发构建工具开发工具

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) 中:

  1. 先通过 ChannelReader.getMap(apkFile) 读出 APK 中已存在的渠道信息(若 APK 此前已写入过渠道),合并进 newData;
  2. 合并本次传入的 extraInfo,并强制移除其中以 channel 为 key 的项(extraInfo.remove(ChannelReader.CHANNEL_KEY)),防止额外信息污染渠道字段;
  3. 若 channel 非空,则写入 newData.put(ChannelReader.CHANNEL_KEY, channel),其中 CHANNEL_KEY 的值为字符串 "channel"(见 ChannelReader.java);
  4. 将合并后的 Map 通过 new JSONObject(newData).toString() 序列化为 JSON 字符串;
  5. 调用 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),其核心步骤如下:

  1. 定位 ZIP EOCD 与 Central Directory:通过 ApkUtil.getCommentLength 从文件尾部回溯定位 ZIP 的 End of Central Directory(EOCD),再读取其中的 Central Directory 起始偏移(见 ApkUtil.java);
  2. 定位 APK Signing Block:APK Signing Block 紧邻 Central Directory 之前,通过其尾部 magic("APK Sig Block 42")与 size 字段确定区块位置(ApkUtil.findApkSigningBlock,见 ApkUtil.java);
  3. 解析现有 ID-value 对:将区块内所有 ID-value 对解析成 Map<Integer, ByteBuffer>(ApkUtil.findIdValues);
  4. 校验 v2 签名块存在:若找不到 0x7109871a 对应的 v2 签名块,说明该 APK 未经 V2 签名,直接抛异常拒绝写入;
  5. 执行写/改/删处理器:由 ChannelWriter/PayloadWriter 传入的 ApkSigningBlockHandler 决定如何合并、覆盖或剔除 ID-value 对,最终构造出新的 ApkSigningBlock;
  6. 写回文件:在原 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。

六、使用建议与注意事项

  1. APK 必须经过 V2 签名:写入过程强依赖 APK Signing Block 中的 v2 签名块存在,未用 V2 方案签名的 APK 无法使用本模块;同时,使用 apksigner 重新对 APK 签名会导致已写入的渠道信息丢失,需要再次写入渠道信息。
  2. 不要动系统保留 id:自定义 id 请避开 0x7109871a、0x42726577 等官方占用 id;额外信息中不要出现以 channel 为 key 的项。
  3. 非 Android 环境需补 org.json 依赖:compile 'org.json:json:20080701';Android 环境直接复用系统自带实现。
  4. 大文件优先 lowMemory:内存敏感场景请使用带 lowMemory 参数的重载。
  5. 读写配对使用:写入时注意与读取端 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 深入阅读源码,可以进一步理解每一步的实现细节。

登录后查看全文
walle