先说个结论如果你在 IntelliJ IDEA 或 Android Studio 里看到 “At least one of the problems in category ‘unused‘ is not analysed due to a compiler option being ignored” 这行提示先别慌它百分之九十不是编译错误更不表示你代码里的未使用问题突然全消失了。这是工具在提醒你由于某个编译器选项被忽略在 “unused” 这一类问题中至少有一个没有被分析到。最近我在整理一个 Kotlin 多模块工程时Problems 面板里就突然冒出过这句话。当时我刚调整完 Gradle 编译配置正准备提交代码面板里这个提示一直悬在那不红不黄既不影响构建又让人觉得哪哪不对劲。后来我专门花了几小时把它彻底查了一遍发现这类问题在团队项目里其实挺常见的——某个人为了压缩编译输出改了一个编译参数结果 IDE 的分析引擎在“unused”这一类检查上直接失效了但表面看起来一切正常。这篇文章我会顺着提示本身往下挖它到底是谁发出的背后涉及哪些编译机制什么时候会触发以及最后怎么定位和解决。内容主要面向用 Kotlin Gradle 的 Android / JVM 项目但对任何使用 IntelliJ 系 IDE 做 Kotlin 开发的工程都有参考价值。新手可以把这当作一个理解编译器诊断机制的小案例老手也可以直接跳到后面的排查清单看有没有踩过同样的坑。1. 提示背后不是 Bug而是“诊断覆盖不完整”1.1 这句话到底是谁在说这个提示的来源不是 Gradle 构建脚本也不是 Kotlin 编译器直接打出来的 error而是 IntelliJ IDEA / Android Studio 的代码分析引擎在整合编译器诊断后发现自己没有覆盖某类问题于是向使用者暴露的一条“信息”。它的关键点有两个一是category ‘unused‘二是compiler option being ignored。先说unused。在 Kotlin 的编译器诊断体系里unused不是某一个检查项而是一整类检查的集合。最常见的包括未使用的局部变量、未使用的私有函数、未使用的构造参数、未使用的导入、未使用的 lambda 参数、未使用的 receiver以及声明了但从未被引用的顶层函数或类。IDE 的 Inspections 面板里对应的是 “Unused declarations” 这一组检查你可以单独控制每个子项的开关和严重程度。1.2 “compiler option being ignored” 意味着什么再看后半句。它说某个“编译器选项被忽略了”。这里藏着一个容易被忽略的事实编译器选项的“最终生效”不等于“配置写法存在”。我见过很多项目在build.gradle.kts里写了一大堆freeCompilerArgs但实际编译时压根没走到那一段配置——比如职责被另一个模块覆盖、DSL 写法更新后旧参数失效、或者版本升级后参数名被改名但不报错。配置存在但选项被忽略这就会让 IDE 的分析引擎得不到它想要的完整语义因此在unused这一类诊断上只能给出部分结果。从这里你也能看出为何这行提示不是出现在编译日志里而是出现在 IDE 的问题面板里IDE 知道它拿到的分析结果是“不完整的”但它不确定这是用户故意为之还是配置意外错误于是用一句客观描述提醒你。这种设计其实相当克制——它没有武断地说“你的项目有问题”而是在说“这里存在一个不确定性请你确认”。1.3 为什么是 “at least one” 而不是具体数量标题里还有一个词值得注意at least one of the problems。为什么不直接说有多少个问题没被分析因为分析引擎目前并不知道具体漏掉了多少个。可能只有一个也可能有一百个它只知道某一类诊断因为没有得到完整的编译器选项而无法继续。这种“未知数”的描述方式恰恰说明处理这个提示的关键不是去统计数量而是先把让诊断无法完整运行的原因找出来。这里我再补充一个场景。如果你在 IDE 里把 “Unused declaration” 检查的 Severity 调高或者启用了allWarningsAsErrors这个提示会显得更刺眼。因为它可能意味着你即将基于一份不完整的分析结果去修代码甚至有人会误以为“当前代码没有任何 unused 问题”而把一些本该清理的私有方法留在仓库里。对于大型项目这种不完整分析带来的长期维护成本可比一个构建错误高得多。2. 常见的触发场景我什么时候会撞上它2.1 场景一Gradle 配置里显式屏蔽了 unused 警告最直接也最常见的原因是项目里有人为了“让编译输出干净一点”在编译器参数中加入了对unused类警告的压制参数。Kotlin 编译器中有类似-Xsuppress-warning这类允许你指定诊断名称的开关。举例来说如果你想压掉某个具体警告可能会写kotlinOptions { freeCompilerArgs freeCompilerArgs -Xsuppress-warningUNUSED_VARIABLE }为了叙述方便我下面用-Xsuppress-warningunused来代表“压制 unused 这一类诊断”的配置实际工程里需要替换成具体的诊断名。写这行配置的人本意可能是想消除编译时满屏的警告噪音。但副作用是IDE 的分析引擎在读到这一配置后会对unused类问题停止完整分析。于是你在 inspection 面板里看不到任何 unused 问题但 IDE 又认为有必要告诉你“分析不完整”于是就有了这个提示。这种场景在团队项目里特别常见某个人为了应付一次构建改了配置然后项目里其它人开始收到这行提示。2.2 场景二增量编译/缓存让诊断结果落后于实际代码第二种常见情况与缓存有关。现在的 Kotlin/Gradle 项目几乎都会开启增量编译配合构建缓存和 IDE 的自身缓存很多问题不会每次都重新分析。当你在分支之间切换或者从远端拉了一版很大改动后老旧的增量缓存和新的编译配置可能产生冲突。IDE 发现当前上下文里有一个编译器选项“应该被处理但实际没处理”就会认为诊断覆盖不完整。这类场景的典型特征是提示出现在某次 Gradle Sync 之后而且你去检查 Gradle 配置没有发现任何问题。处理方式相对温和清理项目缓存、重启 IDE、或者执行一次./gradlew clean重新编译提示通常就消失了。但我要提醒一点——如果清理缓存后它反复出现那说明不是缓存问题而是底层配置问题别用“清缓存”作为唯一的解。2.3 场景三IDE 配置与 Gradle 编译配置不一致第三种场景是 IDE 的 Inspection 设置和 Gradle 实际使用的编译器参数不一致。比如你在 IDE 里把 “Unused declarations” 检查开启了但 Gradle 配置中传给 Kotlin 编译器的参数却包含某些影响 unused 分析的开关或者反过来IDE 已经被告知某个检查完全不用分析而 Gradle 侧仍然在尝试分析。IDE 为了保持一个全局统一的分析模型有时会退而求其次只做有限分析再把这个“降级”通过提示告诉你。在我的经验里这种不一致往往出现在项目从旧版 Kotlin 升级到新版之后。Kotlin 2.0 开始推荐使用compilerOptions {}DSL 而不是旧kotlinOptions {}如果项目里新旧两套配置并存很容易出现某些参数在 IDE 里被视为“未知/忽略”从而触发提示。2.4 场景四多模块项目里配置覆盖问题第四种场景在单体仓库、多模块工程里最明显。假设 A 模块给 Kotlin 编译器加了一个影响 unused 分析的参数B 模块没有但 IDE 做跨模块分析时会把多个模块的编译选项合并在一套上下文里。此时 B 模块的代码中如果有 unused 问题分析引擎可能无法判断应该按哪个编译选项来处理于是打出“至少有一个问题没有被分析”的提示。这种场景排查起来更隐蔽因为你单看 B 模块的 Gradle 配置是完全正常的真正的问题在 A 模块。这些触发场景说明一个核心观点这个提示不是一个孤立 bug而是“编译器选项在真实构建链路中未完全生效”的一种低配版告警。理解到这一步排查思路就清晰了我们要去检查编译链路中所有可能影响unused分析的因素。3. 一步一步定位从复现到找到元凶3.1 先确认提示出现在哪里不要一上来就改代码。先把提示的上下文看清楚。它出现在哪里是 Gradle 构建输出里还是 IDE 的 Problems 面板如果只是 IDE 面板那大概率是 IDE 分析层的问题如果是命令行构建也输出同样的提示那就要认真对待 Gradle 配置了。区分方法很简单在项目根目录执行一次完整编译。./gradlew compileDebugKotlin --rerun-tasks再执行一次带告警统计的编译./gradlew compileDebugKotlin --rerun-tasks --info如果命令行输出里完全没有 “not analysed” 相关文字说明问题只存在于 IDE 的分析引擎侧如果命令行也提示说明你的编译器参数或构建缓存确实出问题了。从这里开始排查路线才会分叉。3.2 审查 Kotlin 编译选项下一步是打开模块的build.gradle.kts检查带kotlinOptions或compilerOptions的部分。我把排查时常用的检查清单列出来你可以直接照着过freeCompilerArgs里有没有-Xsuppress-warning、-Werror、-progressive这类影响诊断行为的参数多个 build.gradle.kts 之间有没有对同一个属性重复赋值比如子模块里freeCompilerArgs ...而在根项目里用freeCompilerArgs listOf(...)覆盖。有没有在gradle.properties里设置kotlin.incrementalfalse/kotlin.compiler.execution.strategy这类会影响编译行为的环境变量如果项目使用 Kotlin 2.x是否还在使用被废弃的kotlinOptions有没有可能新旧 DSL 混用导致参数被忽略3.3 最小化复现砍掉所有“装饰性”配置排查到这一步依然找不到问题的时候我有一个很粗暴但有效的办法搜索整个项目仓库里所有freeCompilerArgs、compilerOptions、kotlinOptions相关配置然后逐个模块做最小化实验。具体做法是在一个模块里临时把编译参数精简到最基础状态只保留目标 JVM 版本和必要的语言版本然后重新 Sync、重新构建看提示是否消失。如果提示消失说明问题一定出在你删掉的某一项参数上如果提示仍在那就把怀疑对象扩大到 IDE 自身的 Inspection 设置和缓存。3.4 用命令行构建结果当“照妖镜”我一直强调一个原则当 IDE 和命令行结论不一致时以命令行构建结果为准。IDE 显示“未分析问题”时命令行构建更接近真相因为 Gradle 会真实地调用 Kotlin 编译器所有配置都会被实际解释一遍。所以如果在上面第 3.1 步中命令行输出正常说明你的代码和构建脚本大概率没有问题提示只是 IDE 分析模型里的一个自我告警处理优先级可以大幅降低。如果你执行--info之后想更细地看编译器到底收到哪些参数还可以在 Gradle 配置里临时打印tasks.withTypeorg.jetbrains.kotlin.gradle.tasks.KotlinCompile().configureEach { doFirst { println(freeCompilerArgs: ${compilerOptions.freeCompilerArgs.get()}) } }编译时就能直观看到每个模块实际传给 Kotlin 编译器的参数列表很多“配置存在但没生效”的问题在这一步就水落石出了。4. 处理方案按优先级推进的四个做法4.1 先校正编译器参数别急着清理缓存如果你在配置里发现确实有压制 unused 警告的参数先问一句这个参数是故意的吗如果是请在注释里写明原因如果不是建议移出。尤其多人维护的项目这类参数很容易是历史遗留——某个版本为了绕过问题暂时加上的后来问题解决了但配置没删。移除方式依据你用的 DSL 版本。新项目建议使用 Kotlin 2.x 的官方 DSLkotlin { compilerOptions { freeCompilerArgs.remove(-Xsuppress-warningunused) } }在 Android 模块里通常写成kotlinOptions { freeCompilerArgs freeCompilerArgs.filterNot { it -Xsuppress-warningunused } }删除后重新 Sync 项目再看 Problems 面板。如果 unused 类问题开始出现说明配置恢复成功之前的提示就是被这个参数压住的。4.2 同步 IDE 检查项让 inspection 和编译诊断一致如果命令行构建正常、编译参数也没有问题那就需要把视角切到 IDE。打开 Settings - Editor - Inspections找到 Kotlin 下面的 “Unused declarations” 相关检查确认它的 severity 符合你的预期。这里有个容易踩的坑很多人为了让“未使用代码”提示更醒目会把 severity 设为 Error同时又在 Gradle 里开了allWarningsAsErrors true。这两个设置单独看都没问题组合在一起之后编译器会尝试把 unused 警告当作错误处理但 IDE 又有自己的“该分析哪些类别”的边界结果两边互相拉扯提示就会出现。我的建议是unused类检查保持 Warning 级别就好不要开到 Error别让本来无害的死代码管理升级成构建失败源头。等真的要推动清理时可以单独通过 CI 脚本或专门的 Gradle task 来做。4.3 清理项目缓存一定要按顺序来确实有一些场景是缓存导致提示暂时性出现。清理的顺序也有讲究我踩过几次坑后形成的顺序是先执行./gradlew clean重新编译项目观察提示是否仍在如果还在关掉 IDE删除.idea目录下除workspace.xml外的配置缓存建议先备份重新打开 IDE 让项目重新导入只有在前面都无效时再考虑File - Invalidate Caches / Restart因为这个操作会清掉本地分析数据重启后需要较长时间重建索引最后检查~/.gradle/caches和项目根目录build文件夹里是否存在异常庞大的缓存这通常是构建缓存被污染的信号。这里有一个需要强调的常识不要因为一行提示就把整个 Gradle 用户目录缓存删掉。删除后所有项目都要重新下载依赖和生成缓存代价远大于收益。先做最小范围的清理。4.4 如果想彻底“无视”这个提示有些团队会决定不处理这个提示。如果确认不是配置问题也不影响实际编译和测试你可以在 IDE 中降低相关 Inspection 的优先级或者把它放到 Ignored 分类里。具体是在 Problems 面板里右键该条提示选择 Ignore 或调整 severity。但这属于治标不治本——后续如果有新人接手看到这个被 ignore 的提示会一脸问号所以我建议至少留下代码注释或团队 wiki 说明。这里也说句实在话如果项目非常庞大分析性能一直紧张主动忽略一些低价值诊断并不是不可接受的工程取舍。关键是这个决定要有意识、有记录地做而不是让问题一直悬着。5. 实战经验常见问题速查与心得5.1 我遇到过的几个典型情况在这里把我在实际项目里遇到的几个案例整理成一个速查表方便你直接对照现象可能的根因处理建议提示只出现在 IDE Problems 面板命令行构建无任何异常IDE 分析模型与 Gradle 编译配置不一致或分析缓存落后先以命令行结果为准清理 IDE 缓存重新 Sync提示在多人协作后突然出现有人提交了带编译参数改动的 Gradle 配置用 git blame 定位改动者确认加参数的目的提示伴随大量 unused 警告一起消失配置里存在压住 unused 诊断的参数移除该参数或改为定向 suppression提示反复出现在同一个模块该模块 freeCompilerArgs 被覆盖或新旧 DSL 混用统一 compilerOptions 配置打印实际参数确认提示在升级 Kotlin/AGP 版本之后出现编译器参数改名或废弃旧配置被静默忽略查阅版本迁移文档更新配置5.2 几个排查过程中的小细节第一优先在--info构建输出里搜一下有没有unused相关字样。Kotlin 编译器在很多情况下会输出类似解释性文字帮你判断是不是这个选项引起的。第二命令行构建时注意避免被增量编译蒙蔽。使用--rerun-tasks强制所有 task 重新执行才有可能拿到完整的警告列表。如果你跑的是带缓存的增量构建那等于还是在看旧结果。第三如果项目里有 compile avoidance 或 remote cache 配置要特别留意。远程缓存会直接复用别人的构建产物如果缓存命中编译参数即使配置错误也可能完全不会暴露。这种情况最坑你代码没问题、本地构建没问题但 CI 上一直出现奇怪提示。5.3 我能给的最实在的建议最后分享一点个人体会。这类“诊断不完整”的提示和普通编译错误不一样它没有强制你说“必须马上改”更像一位细心同事在旁边提醒你“你刚才看到的结论可能不完整”。为了不让这种不确定性长期存在我会给自己定一个简单的处理原则出现提示后先花不超过十五分钟排查配置如果找不到原因就直接用命令行构建结果做对照命令行没有异常的话把提示先降级处理记在待办里而不是盲目改代码。很多时候它最终被证明是一个已经废弃的参数或一次缓存障碍和代码质量没有半点关系。我在实际项目中还有个习惯把所有会影响编译器诊断的参数都集中到一个可注释的配置块里并写明用途。这样后人看到某个全局编译选项时能立刻明白它是用来做什么的什么时候可以安全移除。遇到这个提示时排查范围也会小很多。希望这套方法能让你下次再看到 “At least one of the problems in category ‘unused‘ is not analysed due to a compiler option being ignored” 时少点焦虑多点从容。