生成Android产物的构建中Dokka报错：PsiClassImpl无法转换为PsiJavaFile

这个类型转换异常我之前帮不少开发者排查过，通常和Dokka的文件解析逻辑、代码结构或者依赖兼容性有关，给你梳理几个实用的排查和解决方向：

• 检查代码文件的合规性
  首先排查项目里的Java/Kotlin文件有没有异常结构：比如同一个文件里定义多个顶级Java类、或者Kotlin和Java代码混写在同一个文件中？Dokka在解析这类非标准文件时，可能会错误地将PsiClass实例当成PsiJavaFile处理，从而触发类型转换错误。重点检查近期改动过的文件，看看是不是新增了这类不符合规范的代码。

• 调整Dokka插件版本
  如果你近期升级了Dokka或者Gradle版本，大概率是版本兼容性问题导致的。建议先回退到之前能正常生成文档的Dokka版本，或者尝试升级到最新的稳定版。比如在模块的build.gradle.kts（或build.gradle）中修改版本：

  plugins {
      id("org.jetbrains.dokka") version "1.8.20" // 换成稳定版本
  }
  

• 清理Gradle缓存后重新构建
  Gradle的缓存有时会残留异常的解析数据，导致奇怪的构建问题。执行以下命令彻底清理后重新生成文档：

  ./gradlew clean dokka
  

• 排查自定义Dokka配置
  如果你的项目有自定义的Dokka扩展（比如自定义文档过滤器、处理器），检查这些逻辑中有没有强制类型转换的代码，比如(PsiJavaFile) element这种写法。如果有，要先判断元素类型再进行转换，避免类型不匹配。

• 检查依赖冲突
  项目中的第三方依赖（比如注解处理器、代码分析工具）可能引入了和Dokka依赖的IntelliJ版本不一致的Psi类，导致类型不兼容。可以用以下命令查看依赖树，找出冲突的IntelliJ相关依赖并排除：

  ./gradlew dependencies
  

如果以上方法都没解决问题，建议尝试最小化复现项目：创建一个新的Android库项目，逐步添加原项目的代码、依赖和Dokka配置，直到出现相同报错，这样就能快速定位到具体的触发点。

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