升级Gradle8与JDK17后Android Javadoc构建报错求助

问题背景 #

原Gradle 7 + JDK 1.6环境下使用以下Javadoc任务可正常构建：

task javadoc(type: Javadoc) {
    title = "My Docs v${android.defaultConfig.versionName}"
    failOnError false
    options.memberLevel = JavadocMemberLevel.PUBLIC
    source = android.sourceSets.main.java.srcDirs
    destinationDir = file("${project.rootDir}/docs/")
    classpath += android.sourceSets.main.compileClasspath + android.sourceSets.main.output
    // classpath += project.files(android.getBootClasspath().join(File.pathSeparator))

    // packages to exclude from the docs
    exclude "com/example/README*"

    // workaround for https://github.com/gradle/gradle/issues/19726 when using "exclude"/"include"
    options.addStringOption("-source-path", android.sourceSets.main.java.srcDirs.join(":"))
}

升级到Gradle 8 + JDK 17后出现两类核心错误：

1. 直接运行任务报错：

Execution failed for task ':example:javadoc'.
> path may not be null or empty string. path=''

2. 取消注释android.getBootClasspath()相关代码后，出现Android SDK类找不到的错误：

…/Example.java:21: error: package android.util does not exist
import android.util.Log;

解决方案 #

问题根源是Gradle 8及新版Android Gradle Plugin（AGP）调整了API，旧的classpath和source-path配置方式不再兼容，以下是修正后的配置方案：

1. 替换BootClasspath获取方式 #

Gradle 8中android.getBootClasspath()已被废弃，改用android.bootClasspath属性，确保classpath能正确包含Android SDK的类文件，避免找不到android.util等系统包。

2. 调整Source-Path设置逻辑 #

JDK 17的Javadoc工具对-source-path参数处理更严格，改用Gradle Javadoc任务的options.sourcePath直接赋值，替代手动拼接字符串的方式，避免空路径报错。

3. 完善Classpath组合规则 #

确保classpath同时包含编译依赖、项目输出目录以及Android SDK的bootclasspath，覆盖所有需要的类文件。

修正后的完整Javadoc任务 #

task javadoc(type: Javadoc) {
    title = "My Docs v${android.defaultConfig.versionName}"
    failOnError false
    options.memberLevel = JavadocMemberLevel.PUBLIC
    
    // 配置源码目录
    source = android.sourceSets.main.java.srcDirs
    
    // 配置文档输出目录
    destinationDir = file("${project.rootDir}/docs/")
    
    // 正确组合classpath：编译依赖 + 项目输出 + Android SDK bootclasspath
    classpath = android.sourceSets.main.compileClasspath + 
                android.sourceSets.main.output + 
                project.files(android.bootClasspath)
    
    // 排除不需要生成文档的文件
    exclude "com/example/README*"
    
    // 适配JDK 17的source-path设置方式
    options.sourcePath = android.sourceSets.main.java.srcDirs
}

额外排查点 #

• 若仍有报错，可在任务中添加println(android.bootClasspath)确认路径是否正常，为空则检查Android SDK的配置是否正确。
• JDK 17的Javadoc默认启用严格语法检查，若有未规范的Javadoc注释，可临时添加options.addStringOption("-Xdoclint:none")关闭检查（建议优先修复注释语法问题）。

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