Android构建报错IllegalStateException：类过多时如何定位问题？

嘿，我之前也踩过类似的坑——开发俩月的项目上线前碰到这种 dex 合并时触发的 JSON 解析异常，给你几个亲测有效的排查方向，一步步来定位问题：

1. 先排除基础缓存和构建变体问题 #

这个报错看起来是 dex 合并过程中触发了意外的 JSON 解析错误，首先先做几个快速验证：

• 执行./gradlew clean清除构建缓存，然后重新尝试构建，排除缓存损坏的可能性
• 切换到 Release 构建变体试试，如果 Release 能正常构建，那大概率是 Debug 专属的依赖或配置出了问题

2. 锁定可疑的第三方依赖 #

因为报错明确提到了ExternalLibsDexMerger，重点排查引入的外部库：

• 回忆最近开发中新增的依赖，尤其是涉及 JSON 解析（比如 Gson、Jackson、Moshi）或者带注解处理器的库（比如 Retrofit、Glide），这类库容易在 dex 合并时出现版本冲突或逻辑冲突
• 用./gradlew app:dependencies命令导出完整依赖树，搜索有没有重复的 JSON 解析库版本（比如同时引入了不同版本的 Gson），版本冲突很可能导致解析逻辑混乱
• 尝试逐个移除最近新增的依赖，每次移除后重新构建，看报错是否消失——这是快速定位问题依赖的笨办法，但很有效

3. 检查构建脚本的配置问题 #

有时候构建配置的错误也会触发这类奇怪的报错：

• 检查app/build.gradle中的dexOptions配置，比如preDexLibraries是否设置合理，不合理的预 dex 配置可能导致依赖包处理异常
• 看看 Debug 模式下是否开启了混淆/代码收缩，如果开启了，临时关闭试试——混淆规则错误可能导致某个 JSON 相关的类被错误处理，进而在 dex 合并时触发解析异常
• 确认android.defaultConfig中的multiDexEnabled是否正确设置（类过多时必须开启），配置错误也可能引发 dex 合并问题

4. 查看详细构建日志找触发点 #

默认的报错信息太笼统，需要开启详细日志定位具体位置：

• 执行./gradlew assembleDebug --info（或--debug，日志更详细），在输出的日志中搜索Expected BEGIN_ARRAY but was STRING，找到完整的栈跟踪信息——栈里会显示具体是哪个类、哪个依赖包触发了这个解析错误
• 如果日志太长，可以重定向到文件方便搜索：./gradlew assembleDebug --info > build_log.txt，然后用文本编辑器打开搜索关键词

5. 清理本地开发环境缓存 #

有时候本地环境的缓存损坏也会导致莫名其妙的问题：

• 清理 Android Studio 的缓存：点击File → Invalidate Caches...，勾选"Invalidate and Restart"，重启后再尝试构建
• 手动删除本地 Gradle 缓存目录~/.gradle/caches，然后重新下载依赖——缓存的依赖包损坏可能引发各种奇怪的构建错误

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