APK 与 AAB 的最终合成路线与 V1/V2/V3 签名原理
APK 和 AAB 是 Android 构建管线的最终交付形态，但它们面向的对象不同：APK 面向设备安装，AAB 面向应用商店分发和动态拆包。
AGP 在前面阶段已经准备好 dex、resources.arsc、Manifest、assets、native libs 和 metadata。最终打包阶段要把这些产物装进特定容器，并通过签名证明“这个包确实来自持有私钥的发布者，且内容没有被篡改”。
APK 的容器本质
APK 本质上是一个带 Android 约束的 ZIP：
app-release.apk
├── AndroidManifest.xml
├── classes.dex
├── resources.arsc
├── res/...
├── assets/...
├── lib/arm64-v8a/*.so
└── META-INF/...
设备安装 APK 时，PackageManager 会解析 Manifest、校验签名、提取或映射 dex/native libs、登记 package 信息。签名不只是发布流程的一步，它参与 Android 应用身份模型：同一应用升级必须满足签名兼容规则。
AAB 是发布中间格式
AAB 不是直接安装到普通设备的格式。它把应用拆成 base module、dynamic feature、配置维度资源和 native 库，交给 Google Play 或 bundletool 生成面向具体设备的 APK set。
app.aab
|
v
bundletool / Play
|
+-- base-master.apk
+-- config.arm64_v8a.apk
+-- config.xxhdpi.apk
`-- feature-xxx.apk
AAB 的价值是减少设备下载体积：设备只拿自己需要的 ABI、density、language 和动态功能模块。代价是发布链路更依赖 bundletool/商店签名体系，本地排障也要理解 APK set。
V1 签名：基于 JAR 的文件级签名
V1 签名继承 JAR 签名机制，核心文件在 META-INF/ 下。它对每个 ZIP entry 记录摘要，再签名摘要文件。
META-INF/MANIFEST.MF
META-INF/CERT.SF
META-INF/CERT.RSA
V1 的问题是它不覆盖 ZIP 容器的所有结构，例如某些元数据变化不一定被完整保护。它主要用于兼容旧 Android 版本。
V2/V3 签名：覆盖整个 APK 内容
V2 签名引入 APK Signing Block，位于 ZIP Central Directory 之前。它对 APK 内容做更完整的块级签名校验，安装时不需要逐个解压文件计算 JAR 签名。
[ZIP entries]
[APK Signing Block: v2/v3 signatures]
[ZIP Central Directory]
[End of Central Directory]
V3 在 V2 基础上加入 key rotation 相关信息，让应用升级过程中可以表达新旧签名证书的信任关系。
这解释了一个关键约束：签名之后再修改 APK 内容，会破坏 V2/V3 签名。任何 zipalign、重打包、渠道写入都必须发生在签名前，或使用支持签名块的正确工具链。
debug 签名与 release 签名
Debug 构建通常使用本机 debug keystore，目的是方便安装调试。Release 构建必须使用受保护的发布 key 或 upload key。
android {
signingConfigs {
create("release") {
storeFile = file(providers.gradleProperty("RELEASE_STORE_FILE").get())
storePassword = providers.gradleProperty("RELEASE_STORE_PASSWORD").get()
keyAlias = providers.gradleProperty("RELEASE_KEY_ALIAS").get()
keyPassword = providers.gradleProperty("RELEASE_KEY_PASSWORD").get()
}
}
}
示例表达的是方向：敏感信息不应硬编码进仓库。实际工程还要结合 CI secret、Play App Signing、权限审计和 key 轮换策略。
签名错误的底层含义
常见安装错误：
| 错误现象 | 底层原因 |
|---|---|
INSTALL_FAILED_UPDATE_INCOMPATIBLE |
已安装应用与新 APK 签名不兼容 |
| 安装包解析失败 | APK 结构或签名块损坏 |
| Play 上传拒绝 | AAB/APK 使用了错误 key 或版本配置 |
| 修改渠道后无法安装 | 签名后又改包内容 |
不要把签名视为最后一个可随手补的步骤。签名定义了应用身份，影响升级、安全沙箱、sharedUserId 历史行为、应用商店分发和崩溃符号文件关联。
工程风险与观测清单
APK 与 AAB 的最终合成路线与 V1/V2/V3 签名原理 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。
因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。
关键风险矩阵
| 风险点 | 触发条件 | 直接后果 | 观测方式 | 缓解策略 |
|---|---|---|---|---|
| 输入声明缺失 | 构建逻辑读取未声明文件或环境变量 | UP-TO-DATE 或缓存结果错误 | 使用 --info 和 Build Scan 查看输入变化 |
把所有影响输出的状态建模为 @Input 或 Provider |
| 绝对路径泄漏 | 任务 key 包含本机路径 | CI 与本地缓存无法复用 | 对比不同机器的 cache key 变化 | 使用相对路径敏感性和路径归一化 |
| 配置期副作用 | build script 执行 I/O、Git、网络请求 | 任意命令都变慢，configuration cache 失效 | 执行 help --scan 观察配置期耗时 |
把副作用移动到任务动作并声明输入输出 |
| Variant 污染 | 对所有 variant 注册重型任务 | debug 构建被 release 逻辑拖慢 | 查看 realized tasks 和 task timeline | 使用 selector 精确匹配目标 variant |
| 权限外溢 | 插件或脚本读取 CI secret、用户目录 | 构建不可复现，存在供应链风险 | 审计构建日志和环境变量访问 | 使用最小权限和显式 secret 注入 |
| 并发竞争 | 多个任务写同一输出目录 | 产物互相覆盖或偶发失败 | 检查 overlapping outputs 报告 | 每个任务拥有独立输出目录 |
| 缓存污染 | 不可信分支向远程缓存 push | 全团队复用错误产物 | 统计 remote cache push 来源 | 只允许受信任 CI 写入远程缓存 |
| 回滚困难 | 构建逻辑与业务变更混在一起 | 发布失败时无法快速定位 | 变更审计和构建 scan 对比 | 构建逻辑独立提交、独立验证 |
| 降级缺口 | 新 Gradle/AGP API 无兜底策略 | 升级失败后阻塞全线开发 | 记录兼容矩阵和失败任务 | 保留可回滚版本和迁移开关 |
| 资源释放遗漏 | 自定义任务打开文件句柄或进程未关闭 | Windows/CI 上清理失败或锁文件 | 观察 daemon 日志和文件锁错误 | 使用 Worker API 或 try/finally 释放资源 |
需要持续观测的指标
- 配置阶段耗时是否随模块数量线性或超线性增长。
- 单次本地 debug 构建的关键路径任务是谁。
- CI clean build 与 incremental build 的耗时差距。
- 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
- Configuration Cache 的命中率和失效原因。
- Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
- 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
- 自定义插件是否提前实现了无关任务。
- 构建日志中是否出现未声明输入、重叠输出、deprecated API。
- 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
- 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
- 变更是否影响开发构建、测试构建和发布构建三条路径。
回滚与降级策略
- 构建逻辑变更与业务代码变更分开提交，便于二分定位。
- Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
- 新插件能力先只接入一个低风险模块，再扩大到全工程。
- 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
- 新增插桩、生成代码、资源处理逻辑必须提供开关。
- 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
- 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
- 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。
最小验证矩阵
| 验证场景 | 命令或动作 | 期望信号 |
|---|---|---|
| 空任务配置成本 | ./gradlew help --scan |
配置期没有无关重任务 |
| 本地增量构建 | 连续执行同一 assemble 任务 | 第二次大量任务 UP-TO-DATE |
| 缓存复用 | 清理输出后启用 build cache | 可缓存任务出现 FROM-CACHE |
| Variant 隔离 | 分别构建 debug/release | 只出现目标 variant 相关任务 |
| CI 可复现 | 干净工作区执行 release 构建 | 不依赖本机隐藏文件 |
| 依赖稳定 | 执行 dependencyInsight | 版本选择可解释，无动态漂移 |
| 配置缓存 | --configuration-cache 连跑两次 |
第二次复用配置缓存 |
| 发布审计 | 记录 scan、mapping、签名信息 | 产物可追溯、可回滚 |
审计问题
- 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
- 它是否读取了没有声明为输入的文件、环境变量或系统属性。
- 它是否在配置阶段执行了本应放到任务动作里的工作。
- 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
- 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
- 它是否把权限、密钥、签名文件路径写进了仓库。
- 它是否破坏了并发执行，例如多个任务写同一个目录。
- 它是否能在失败时输出足够日志，帮助定位根因。
- 它是否能通过一个开关降级，避免阻塞全工程构建。
- 它是否有最小复现样例或 TestKit/集成测试覆盖。
- 它是否会让下游模块承担不必要的依赖或任务成本。
- 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。
反模式清单
- 用
clean掩盖输入输出声明错误。 - 用
afterEvaluate修补本可以用 Provider 表达的依赖关系。 - 用动态版本解决依赖冲突，却让构建不可复现。
- 把所有公共配置塞进一个巨型 convention plugin。
- 在 debug 构建默认开启 release 级别的重型优化。
- 在任务动作里读取
project或全局 configuration。 - 在多个任务中共享同一个临时目录。
- 缓存命中率异常时只重启 CI，不分析 miss reason。
- 把构建扫描链接当作可选附件，而不是性能回归证据。
- 用本地 IDE 成功运行证明 CI 发布链路安全。
最小实操脚本
./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath
这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 APK 与 AAB 的最终合成路线与 V1/V2/V3 签名原理 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。