企业官网建设流程全解析

前阵子组长丢给我一个需求：把app-release.apk按 12 个市场渠道重新打一遍包。一开始我觉得很简单，不就是 Gradle 里的productFlavors配一下嘛，结果跑一次全量构建 40 多分钟，中途产品又改了一次渠道名单，等于白等一趟。后来我干脆自己做了一个“主包只打一次、脚本批量补渠道号”的小工具——核心就是用 Android 新版的 v2 签名方案，把渠道信息塞进 APK 的APK Signing Block里，不重新构建、不重新签名，秒出所有渠道包。

这篇文章想把 v2 签名和渠道包这两件事彻底讲透：v1 和 v2 到底差在哪、为什么以前用 zip 注释写渠道号的老办法在 v2 时代会失效、以及一套能直接抄作业的自研渠道包工具的完整实现思路。适合独立开发者、中小团队里负责打包发版的 Android 开发，也适合那些想在 CI/CD 里省掉一大截构建时间的同学。

1. 为什么 v2 签名时代，传统渠道包方案玩不转了

1.1 v1 和 v2 签名的核心差异

先回顾一下 APK 签名的演进。v1 签名也就是传统的 JAR 签名，从 Android 诞生第一天就有，它做的事情是逐一对 APK 里的每个文件计算摘要，然后把这些摘要写进META-INF/目录下的.SF和.RSA文件。安装的时候系统逐个文件解压、算摘要、跟签名文件比对。这套方式的优点是灵活，缺点是慢，而且保护粒度太细，APK 里哪怕有一堆文件没被校验到，也不影响安装。

v2 签名是 Android 7.0 开始引入的，官方叫APK Signature Scheme v2。它不再逐个文件处理，而是把整个 APK 当成一个大文件，用特殊方式计算摘要，然后把摘要和证书信息放进一个专门的区域——APK Signing Block。安装时系统一次性校验整个 APK 的完整性，任何字节被改动都会导致校验失败。v3 签名在 Android 9 上又做了一次升级，支持密钥轮转，但底层思路和 v2 一致。

打个比方，v1 像是给每个快递盒单独贴封条，v2 像是给整个集装箱焊了一圈封条。v1 时代你把盒子里某个泡沫挪个位置，封条不受影响；v2 时代你碰一下箱子哪怕换个螺丝，封条当场失效。

1.2 老办法“改 zip 注释写渠道”为什么会失效

早年间做渠道包，很多方案都依赖一个特性：APK 本质是个 zip 包，zip 格式允许在文件末尾的注释区（EOCD comment）写自定义数据。v1 签名不校验这段注释，所以往里面塞一个渠道号，APK 的签名依然有效，应用市场也能通过包名加渠道号区分渠道。

这个方案在 v1 时代很香，因为零成本、不用重打包、不用重新签名。但 v2 签名出现后，整个局面变了：v2 的摘要覆盖了 APK 文件中除签名块本身之外的几乎全部内容，包括 zip 中央目录和 EOCD。你一旦动了注释区，哪怕只多一个字节，v2 校验就会失败。

更麻烦的是，Android 7.0 及以上系统在安装 APK 时，如果检测到包里有 v2 签名块，会优先用 v2 规则做完整性校验。也就是说，你想“只用 v1 签名，不签 v2”来规避这个问题，会在新系统上直接被拒之门外。唯一正确的方向，就是顺着 v2 的设计思路走：既然签名块本身开放给开发者做自定义数据扩展，那渠道信息就放到签名块里去。

2. 渠道包工具的方案选型与整体设计

2.1 主流多渠道打包方案横向对比

市面上做渠道包的成熟方案不少，我在动手前把主流的都过了一遍，思路归纳下来大致分三类。

2.2 为什么我选择“主包一次签名，脚本注入渠道”

我当时权衡了很久，最终决定不自找麻烦去搞一套完整的重建流程，而是把工具定位成“签名后处理脚本”。核心思路很简单：主包用标准流程构建好，签名、对齐都做完整，然后脚本把渠道号批量写进 APK 的签名块。

这个方案有几个非常实际的好处。

第一，快。一次构建出一个基准包，后续每个渠道包只是复制文件加改签名块，毫秒级完成。对比 Gradle 重打包动辄半个小时的构建，体验是天壤之别。

第二，对现有工程零侵入。不需要在build.gradle里加一堆productFlavors的配置，也不需要在代码里写一堆BuildConfig.FLAVOR之类的条件判断。打包组拿到的产物和普通 APK 完全一致。

第三，渠道信息写在签名块里，签名验证会天然忽略这个区域，所以不需要重新签名。这样既保证了 APK 的签名完整，又留出了渠道扩展空间，是 v2 签名在设计阶段就留好的路子。

2.3 工具的使用流程与功能清单

我最终做出来的工具是一个命令行脚本，调用方式长这样：

python make_channels.py -i app-release.apk -c channels.txt -o ./output

channels.txt每行写一个渠道号，支持#注释。脚本会先校验基准包的 v2 签名，确认没问题后遍历渠道列表，逐个生成渠道包。

工具的功能清单大致如下：

• 自动识别并校验 APK 的 v2/v3 签名状态
• 从渠道列表文件批量读取渠道号，支持去重
• 在 APK Signing Block 中插入自定义 ID-value 渠道信息
• 自动同步更新 EOCD 中的中央目录偏移
• 输出渠道包清单，包含包名、大小、MD5、生成时间
• 支持指定输出目录，支持对已加固 APK 做二次签名后注入

3. 核心实现：v2 签名与渠道注入的实操细节

3.1 准备一个规范的 v2 签名基准 APK

在动脚本之前，先把基准包生成对。Android Studio 里配置签名信息，常规写法如下：

android { signingConfigs { release { storeFile file("../keystore/release.jks") storePassword "your-store-password" keyAlias "release" keyPassword "your-key-password" } } buildTypes { release { minifyEnabled true shrinkResources true signingConfig signingConfigs.release } } }

需要注意，build-tools 版本要足够新，至少 24.0.3 以上才有apksigner工具，也才有完整的 v2 签名输出。我建议直接用 Android Studio 自带的 build-tools，基本都在最新版本。

如果你不走 Gradle，想手动签名，可以这样：

# 先对齐，再签名，顺序不能反 zipalign -v -p 4 app-release-unsigned.apk app-release-aligned.apk # 使用 v2、v3 签名 apksigner sign \ --ks release.jks \ --ks-key-alias release \ --ks-pass pass:123456 \ --out app-release.apk \ app-release-aligned.apk

签名完成后，用下面这行命令验证签名信息：

apksigner verify --verbose --print-certs app-release.apk

输出里可以看到v2: true、v3: true这样的签名标记，以及证书的 SHA256 指纹。顺便说一句，做微信开放平台、高德地图之类的 SDK 授权时，后台填的签名 MD5 或 SHA1，也可以用--print-certs拿。

这里有一个非常关键的注意事项：zipalign必须排在apksigner sign前面。因为zipalign会调整 zip 文件内部条目的字节偏移，如果先签名再对齐，v2 签名摘要会被破坏，包就废了。

3.2 APK 的字节结构与签名块注入原理

要把渠道信息写进签名块，必须先搞清楚 APK 的字节布局。一个完整的 APK 文件，从前往后分别是这样几段：

1. zip 本地文件条目区，也就是所有文件内容按顺序排列的区域
2. APK Signing Block，v2/v3 签名数据存在这里
3. zip 中央目录，记录每个条目的元信息
4. EOCD，记录中央目录的偏移和总大小

APK Signing Block的格式是：

[uint64 size1] [ID-value 对序列] [uint64 size2] [16字节 magic: "APK Sig Block 42"]

其中size1和size2的值相同，表示从 ID-value 区域开始到 magic 末尾的长度。ID-value 对本身也是一个嵌套结构：先是 uint64 表示整对的长度，然后是 uint32 的 ID，最后是 ID 对应的数据内容。

v2 签名在校验时，会忽略整个 APK Signing Block 区域，也就是size1到magic之间的部分。所以我们可以在这个区域里新增一个自定义 ID-value 对，写入渠道号信息，而不影响签名有效性。渠道号一般用0x71777777这个 ID，这是行业内比较通用的“通用渠道”标识 ID，Walle 也用的这个值。

这里有个容易踩坑的细节：插入新的 ID-value 对之后，签名块的长度变了，而签名块位于中央目录之前，所以中央目录在文件中的偏移也会跟着变。EOCD 里记录中央目录偏移的字段必须同步更新，否则安卓系统解析 APK 时会直接报错，安装提示“解析包时出现问题”。

3.3 核心注入代码实现

我写了一个 Python 版本的脚本，核心分三步：定位签名块、构造 ID-value 对、重组文件并更新 EOCD。

import struct import os V2_MAGIC = b'APK Sig Block 42' CHANNEL_BLOCK_ID = 0x71777777 EOCD_MAGIC = b'\x50\x4b\x05\x06' MAX_COMMENT_SIZE = 65535 def read_eocd(data): # zip 的 EOCD 在文件末尾，前面可能带注释，所以从后往前找 for i in range(len(data) - 22, max(0, len(data) - 22 - MAX_COMMENT_SIZE), -1): if data[i:i + 4] == EOCD_MAGIC: fields = struct.unpack_from('<HHHHIIH', data, i + 4) _, _, _, _, _, cd_offset, _ = fields return i, cd_offset raise ValueError('EOCD not found') def find_signing_block(data, cd_offset): # 签名块紧挨在中央目录前面，末尾是 magic 和 size if cd_offset < 24: return None magic = data[cd_offset - 16:cd_offset] if magic != V2_MAGIC: return None size_field = struct.unpack_from('<Q', data, cd_offset - 24)[0] block_start = cd_offset - (size_field + 8) return block_start, cd_offset def parse_id_value_pairs(data, block_start, block_end): pairs = {} pos = block_start + 8 while pos < block_end - 24: pair_len = struct.unpack_from('<Q', data, pos)[0] pair_id = struct.unpack_from('<I', data, pos + 8)[0] pair_value = data[pos + 12:pos + 8 + pair_len] pairs[pair_id] = pair_value pos += 8 + pair_len return pairs def build_signing_block(pairs): inner = b'' for pair_id, pair_value in pairs.items(): pair_data = struct.pack('<I', pair_id) + pair_value inner += struct.pack('<Q', len(pair_data) + 4) + pair_data block_size = len(inner) + 24 return struct.pack('<Q', block_size - 8) + inner + \ struct.pack('<Q', block_size - 8) + V2_MAGIC def inject_channel(apk_path, channel, out_path): data = bytearray(open(apk_path, 'rb').read()) eocd_index, cd_offset = read_eocd(data) block_start, block_end = find_signing_block(data, cd_offset) if block_start is None: raise RuntimeError('APK 中没有找到 v2 签名块，请确认基准包已使用 v2 签名') pairs = parse_id_value_pairs(data, block_start, block_end) pairs[CHANNEL_BLOCK_ID] = channel.encode('utf-8') new_block = build_signing_block(pairs) new_file = data[:block_start] + new_block + data[block_end:] # 新签名块会占用不同长度，中央目录整体位移，需更新 EOCD new_cd_offset = block_start + len(new_block) cur_offset = eocd_index + 16 struct.pack_into('<I', new_file, cur_offset, new_cd_offset) with open(out_path, 'wb') as f: f.write(new_file)

脚本的核心逻辑不复杂，但有一个地方值得多说一句：build_signing_block里构造 ID-value 对时，pair_len指的是从 ID 字段开头到该对结束的长度。我在最初版本里把这个长度算了两次，结果所有渠道包都装不上，后来对着签名块规范逐字节核对才找到问题。如果你也想自己实现，建议写完之后用apksigner verify -v验证一遍所有生成的渠道包。

3.4 操作顺序与“对齐、签名、注入”的坑

在实际使用中，我最常被问到的一个问题是：为什么zipalign必须在签名前做，而渠道注入可以放在签名后？

原因在于：zipalign会改动 zip 条目的本地文件头和字节对齐方式，它会改变 APK 的字节内容，所以必须在 v2 签名之前执行，确保签名后的 APK 不再发生字节变化。而渠道注入只修改签名块内部数据，以及 EOCD 中记录的中央目录偏移，这两处都不在 v2 摘要的保护范围内，所以注入后不需要重新签名。

因此，一个规范的打包流程是：

gradle assembleRelease # 1. 出未签名包 zipalign -v -p 4 in.apk aligned.apk # 2. 对齐 apksigner sign ... aligned.apk # 3. v2/v3 签名 python make_channels.py ... # 4. 注入渠道

如果项目里有加固需求，顺序就变成：原包 -> 加固 -> 重新签名 -> 注入渠道。加固工具会解包再封包，原有的签名块会被直接扔掉，所以必须在加固后重新签名，再走渠道注入。

4. 常见问题与排查技巧实录

4.1 安装报错“解析包时出现问题”或“App not installed”

这类问题八成出在签名块本身被改坏了。排查思路按下面三步走：

先跑apksigner verify --verbose app-release.apk，确认 v2/v3 签名状态是否为 true。如果显示 v2 校验失败，说明注入或者签名环节改动了受保护区域。

再跑zipalign -c -v 4 app-release.apk，检查对齐状态。如果输出里出现Verification FAILED，说明对齐被破坏，需要重新走一遍标准流程。

最后检查脚本是否更新了 EOCD 的中央目录偏移。这个偏移如果没更新或者更新错了地方，APK 在解析阶段就找不到中央目录，系统会直接判定包损坏。我见过太多人把偏移写进了 EOCD 的注释区，结果就是包能生成，但装不上。

4.2 加固后的渠道包需要二次签名

如果你用腾讯乐固、360 加固之类的工具，请务必记住一个流程：先加固，再签名，最后注入渠道。

加固过程会把 APK 进行解包、加密、重打包，原有的 v2 签名块会被破坏甚至删除。所以加固后的 APK 必须重新跑一遍apksigner sign，然后再用渠道脚本做注入。如果反过来，先注入渠道再加固，渠道信息会被加固过程冲掉，等于白干。

另外，有些加固服务商会提供一个“自动签名”开关，默认开启。如果你自己也要再签一次，注意别签两次导致证书不一致。建议加固时关掉自动签名，统一用自己手里的 jks 走一遍标准签名流程。

4.3 运行时渠道号读不到

渠道号写入签名块后，App 里需要在运行时自己把它读出来。这里分享一个关键经验：一定要通过context.getApplicationInfo().sourceDir拿到 APK 文件路径，然后按同样的解析逻辑去读签名块里的 ID-value。

不要尝试去读/storage/emulated/0/Android/data/...这种外部存储路径，那里面一般没有安装包文件，而且不同厂商的 FileProvider 还会继续把路径改来改去。运行时读取渠道号的 Java 核心代码大概是这样的：

public static String getChannel(Context context) { try { File apkFile = new File(context.getApplicationInfo().sourceDir); // 1. 读取文件尾部 EOCD // 2. 通过中央目录偏移定位签名块 // 3. 遍历 ID-value，找到 0x71777777 对应的值 } catch (Exception e) { return ""; } return ""; }

注意一点：读取渠道号的逻辑只跟 APK 文件结构有关，不依赖系统版本是不是 7.0 以上。就算手机是 Android 6.0，只要 APK 里存在 v2 签名块，你也能解析出来。真正的问题会出现在设备上的包如果被某个渠道做了二次处理，把签名块冲掉了，那就读不到了。这种情况在海外发行、接入某些 SDK 后偶尔会遇到，排查时先apksigner verify看一下线上包的签名块结构。

4.4 批量出包时的文件一致性校验

渠道包数量一多，最怕的就是漏包、混包、或者生成到一半中断。我在脚本里加了两个保险：

一个是在生成时对每个渠道包计算 MD5，最后输出一张清单表格，包含渠道名、文件大小、MD5、生成时间。交付给测试或者上传应用市场时，这张表格直接可以作为附件。

另一个是渠道列表去重。以前我用过一个渠道名单，里面huawei和HUAWEI都出现了，结果生成了两个完全一样的包，上传时差点重复上架。现在脚本启动时会先做一次去重和大小写统一，提醒操作者确认。

4.5 环境问题：apksigner 找不到、JDK 版本冲突

apksigner依赖 Java 8 及以上环境，所以在 CI 机器上跑的时候，经常遇到UnsupportedClassVersionError之类的报错。解决方法是把 JDK 统一到 11 或 17，并在脚本里显式指定JAVA_HOME。

同时，apksigner位于 Android SDK 的build-tools目录下，版本有很多个。脚本里建议自动探测最新版本：

BUILD_TOOLS=$(ls $ANDROID_HOME/build-tools/ | sort -V | tail -1) APKSIGNER=$ANDROID_HOME/build-tools/$BUILD_TOOLS/apksigner

这样不管构建机上的 build-tools 装了多少个版本，都能自动找到最新版，避免因为版本太旧导致 v2 签名功能缺失。

最后再分享一个小细节

这个工具我用到现在已经快两年了，打包流程彻底稳定下来后，基本没再出过乱子。我个人的体会是：渠道包工具这类事情，最怕的不是实现复杂，而是你没有一个固定顺序。只要把“先对齐、再签名、最后注入渠道”这个顺序焊死在流程里，剩下的就都是体力活了。

还有一个小技巧：渠道号的命名尽量用英文、拼音或数字，不要用中文。中文字符在部分统计平台的 URL 回传里会乱码，渠道数据直接对不上，后期排查起来特别麻烦。建议团队内部统一好渠道命名规则，比如都用小写加下划线，写入channels.txt之前先过一遍脚本做格式校验。

如果你所在的团队发版频繁、渠道动不动就二三十个，完全可以照着这个思路做一套属于你们自己的打包流水线。先把原理搞清楚，再决定是直接用 Walle 还是自研脚本。对我来说，自己把签名块解析写一遍，比单纯调别人封装好的库更让人踏实，因为出问题的时候，你能第一时间定位到根因。