M1芯片Mac Android Studio Kapt Room构建失败排查

问题复现 #

搭载Apple M1（aarch64架构）芯片的MacBook Pro导入Android项目后，仅该设备出现构建失败，其余x86架构设备构建正常，故障分两个阶段：

• 初始报错：执行org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask$KaptExecutionWorkAction时触发故障，:appmanager:kaptProdDebugKotlin任务执行失败，堆栈定位为Room依赖缺少适配Mac aarch64架构的SQLite原生库
• 升级报错：将Room版本升级至2.4.2解决原生库缺失问题后，抛出新异常java.lang.IllegalArgumentException，提示@androidx.room.Database注解未定义autoMigrations()元素，构建仍失败

根因说明 #

1. 第一阶段原生库缺失问题：2.4.0以下版本的Room未提供适配Apple Silicon系列芯片的aarch64架构SQLite原生库，KAPT处理Room注解时无法加载对应本地依赖直接报错
2. 第二阶段注解属性缺失问题：Room从2.4.0版本开始才在@Database注解中新增autoMigrations属性，配套注解处理器会读取该属性生成自动迁移逻辑。如果升级时只单独修改了某一个Room组件的版本，或是其他三方库传递依赖拉入了低于2.4.0版本的Room公共组件（包含注解定义的room-common），Gradle依赖仲裁会选中低版本的注解类，高版本注解处理器执行时尝试读取不存在的autoMigrations属性，就会抛出参数异常。

修复步骤 #

• 统一全项目所有官方Room组件的版本号，确保room-runtime、room-compiler、room-ktx、room-testing等所有Room相关依赖使用完全一致的2.4.x及以上稳定版本，禁止单独升级某一个组件。参考配置如下：

  // 在模块build.gradle中配置，建议在根目录build.gradle或版本目录统一定义版本号避免漏改
  def room_version = "2.4.3" // 可选择2.4.2及以上的2.4序列正式稳定版
  implementation "androidx.room:room-runtime:$room_version"
  kapt "androidx.room:room-compiler:$room_version"
  implementation "androidx.room:room-ktx:$room_version"
  

• 排查依赖树解决版本冲突：在项目根目录执行./gradlew :appmanager:dependencies（将appmanager替换为报错对应的模块名），输出的依赖树中搜索androidx.room条目，找到所有版本低于2.4.0的传递依赖项，通过exclude规则排除低版本的Room传递依赖，避免低版本类覆盖高版本。
• 清理缓存后重新构建：

  ./gradlew clean
  

  若清理后仍报错，可手动删除项目根目录.gradle/caches下的Room相关缓存文件，避免旧缓存干扰构建。
• 如果项目使用KSP替代KAPT处理注解，需保证KSP对应的Room处理器版本和其他Room组件版本完全一致，版本不匹配同样会触发该异常。

补充：如果暂时无法升级Room版本，也可以通过右键点击Android Studio图标，勾选「使用Rosetta打开」的方式转译运行，绕过aarch64原生库缺失问题，但该方案会降低IDE运行速度，优先推荐升级统一Room版本的方案。

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