真机运行Android项目报资源链接失败mipmap/app_icon缺失如何修复

该报错是Android资源打包工具AAPT在执行全量资源链接时，无法找到声明的mipmap/app_icon资源导致的。模拟器能正常运行是因为之前的增量构建残留了旧缓存，没有触发完整的资源校验流程，真机运行触发全量打包才暴露问题，常见诱因有三类：

• 图标文件存放路径错误、文件名拼写不规范：比如把图标放到了build缓存目录而非源码res目录、文件名含大写/横杠等非法字符、大小写和引用名不匹配（Linux文件系统大小写敏感，Windows/macOS默认大小写不敏感，本地开发时很容易忽略这个问题）
• 资源目录结构不完整：图标只放到了部分dpi的mipmap文件夹，没有覆盖全量资源配置
• 构建缓存损坏：之前的增量构建把资源索引表搞乱，导致新加入的资源没有被正确收录

按以下顺序排查处理即可：

• 核对资源存放位置和文件名
  确认app_icon.png文件存放在android/app/src/main/res/下的各mipmap密度目录中，标准目录结构参考：

  android/app/src/main/res/
  ├─ mipmap-mdpi/
  │  └─ app_icon.png
  ├─ mipmap-hdpi/
  │  └─ app_icon.png
  ├─ mipmap-xhdpi/
  │  └─ app_icon.png
  ├─ mipmap-xxhdpi/
  │  └─ app_icon.png
  └─ mipmap-xxxhdpi/
     └─ app_icon.png
  

  注意：文件名必须全小写，仅允许使用小写字母、数字、下划线，不能包含大写字母、横杠、空格或其他特殊字符，文件名必须和引用的app_icon完全一致
• 确认引用配置正确性
  当前Manifest中配置的android:icon="@mipmap/app_icon"、以及通知初始化代码里的AndroidInitializationSettings('app_icon')写法是正确的，不需要额外加文件后缀。
• 清理损坏的构建缓存后重新构建
  在项目根目录依次执行以下命令，彻底清空旧构建产物后重新运行：

  flutter clean
  cd android && ./gradlew clean && cd ..
  flutter pub get
  flutter run
  

• 特殊场景排查
  如果上述操作后还是报错，检查两个配置点：
  1. 确认图标文件没有被放到src/debug、src/profile这类非main源码集目录下，非main目录的资源只会在对应构建变体下生效
  2. 检查app模块下的build.gradle文件，确认没有配置把mipmap目录加入资源排除列表的规则

内容的提问来源于stack exchange，提问作者Daniil