AAPT2 资源编译全流程与 ID 分配与冲突破解策略
AAPT2 是 Android 资源系统的编译器。它把 res/ 目录中的 XML、图片和 value 资源解析、索引、编译成 Android 平台更容易加载的二进制格式，并在 link 阶段生成资源表、R 符号和最终包内资源结构。
资源不是运行时才被简单读取的文件。Android 构建会在编译期给资源建立符号、类型、ID 和引用关系。AAPT2 的价值，就是把松散文件变成可验证、可链接、可被运行时高效查询的资源表。
AAPT2 的两阶段模型
AAPT2 分为 compile 和 link：
res/layout/main.xml
res/values/strings.xml
res/drawable/icon.png
|
v
AAPT2 compile
|
v
compiled .flat files
|
v
AAPT2 link + manifest + dependencies
|
v
resources.arsc + R + packaged resources
compile 阶段处理单个资源文件，尽量做到文件级增量。link 阶段把本模块、依赖模块、Manifest、资源引用关系合并起来，生成最终资源表。
这个拆分和 Java/Kotlin 编译类似：先把单个源文件编成中间产物，再做全局链接。
资源 ID 的结构
Android 资源 ID 通常是 32 位整数：
0xPPTTEEEE
PP: package id
TT: type id
EEEE: entry id
例如：
0x7f010001
0x7f 通常代表应用包资源，01 代表某类资源类型，后面的 entry 表示具体条目。运行时通过这个整数到 resources.arsc 中查询实际资源。
这就是为什么资源系统需要编译期链接。代码里写的 R.string.app_name 最终不是字符串路径，而是一个可以被运行时快速查表的整数 ID。
R 类为什么影响编译增量
传统 Android 工程中，R 字段可能是 public static final int 常量。Java 编译器会把常量内联进使用方 class：
int id = R.string.app_name;
可能被编译成直接使用整数。如果资源 ID 变化，所有内联过这个值的 class 都可能需要重编译。
AGP 推动非 final、非传递 R，就是为了缩小资源变化的影响范围：
- 非 final R：减少常量内联带来的重编译扩散。
- 非传递 R：模块只能直接访问自己的资源，减少跨模块资源符号污染。
这是构建性能优化，不只是 API 风格变化。
资源合并冲突的本质
资源冲突通常来自多个 source set 或依赖提供同名同类型资源：
src/main/res/values/strings.xml -> @string/app_name
src/free/res/values/strings.xml -> @string/app_name
library/res/values/strings.xml -> @string/app_name
合并时 AGP/AAPT2 会根据 source set 优先级、依赖关系和资源类型决定覆盖或报错。并不是所有同名都是错误：flavor 覆盖 main 是合法设计；两个同优先级目录里定义同一资源通常就是冲突。
排查时先看资源来自哪一层：
./gradlew :app:sourceSets
./gradlew :app:mergeDebugResources --info
不要直接改名绕过问题。资源冲突通常反映了模块边界、source set 优先级或依赖引入不清楚。
Manifest 与资源链接
Manifest 中也可能引用资源：
<application
android:label="@string/app_name"
android:theme="@style/AppTheme" />
因此 Manifest merge 和 AAPT2 link 是相互关联的。Manifest 合并后的结果会参与资源链接，资源表中的条目也会影响最终 Manifest 可解析性。
这解释了某些错误为什么出现在 processDebugResources 或 linkDebugAndroidResources，但根源是 Manifest、依赖资源或 flavor source set。
工程实践中的资源边界
大型工程中，资源管理应遵循：
- feature 模块只暴露必要资源，不把公共设计系统复制到每个模块。
- design-system 资源前缀统一，避免和业务资源撞名。
- 开启非传递 R，迫使模块显式依赖资源所有者。
- 不在多个同级资源目录定义相同资源名。
- 使用 AAPT2 报错定位真实文件，而不是盲目 clean。
资源系统的底层是符号链接和 ID 表。只要把它理解成“编译期建立的强类型资源索引”，很多资源玄学问题都会变得可推理。
工程风险与观测清单
AAPT2 资源编译全流程与 ID 分配与冲突破解策略 一旦进入真实 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
这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 AAPT2 资源编译全流程与 ID 分配与冲突破解策略 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。