Java 10下maven-javadoc-plugin的attach-javadocs目标执行失败排查

我帮你梳理下这个Java 10环境下Maven Javadoc插件执行失败的问题，结合你提到的场景和相关问题，咱们一步步来解决：

你在Java 10环境中运行Maven的attach-javadocs目标（使用org.apache.maven.plugins:maven-javadoc-plugin:3.0.0:jar）时遭遇失败，同时你的maven-compiler-plugin配置将<source>和<target>都设为9，这个问题和Java 10升级后Javadoc无法正确链接JDK包的兼容性问题直接相关。

Java 9引入的模块系统在Java 10中又有了细节调整，而maven-javadoc-plugin 3.0.0版本对Java 10的模块路径处理逻辑支持不完善。当你的项目编译时指定了source/target为9，但运行环境是Java 10，Javadoc工具在生成JDK包的链接时，会因为模块系统的兼容性差异抛出错误，最终导致attach-javadocs目标执行失败。

要复现这个问题，可以按以下操作：

• 新建一个简单的Maven项目，在pom.xml中配置maven-compiler-plugin 3.7.0，设置<source>9</source>和<target>9</target>
• 添加maven-javadoc-plugin 3.0.0，并将attach-javadocs目标绑定到构建生命周期
• 把本地JDK环境切换为Java 10
• 执行Maven命令：mvn clean install javadoc:attach-javadocs
• 此时会观察到构建失败，报错信息通常包含Javadoc无法解析JDK包链接的内容

针对这个问题，有几个实用的解决办法，你可以根据项目情况选择：

1. 升级maven-javadoc-plugin到兼容Java 10的版本 #

maven-javadoc-plugin从3.1.0版本开始完善了对Java 9+模块系统的支持，尤其是Java 10的兼容性。推荐升级到3.1.1及以上的稳定版本，修改pom.xml配置如下：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.1.1</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 可选：添加--release参数匹配编译的JDK版本 -->
        <additionalOptions>
            <additionalOption>--release 9</additionalOption>
        </additionalOptions>
    </configuration>
</plugin>

2. 统一编译与运行环境的JDK版本 #

要么将项目的编译配置升级到Java 10，和运行环境保持一致：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.7.0</version>
    <configuration>
        <source>10</source>
        <target>10</target>
        <release>10</release> <!-- 推荐使用release参数，同时指定source和target -->
    </configuration>
</plugin>

要么将本地运行环境切换回Java 9，让Javadoc工具的行为和编译配置匹配，也能避免兼容性冲突。

3. 临时禁用Javadoc检查（仅应急用） #

如果只是需要临时绕过这个问题，可以在maven-javadoc-plugin的配置中添加参数关闭文档检查，但这会忽略所有Javadoc的错误和警告，不建议长期使用：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <additionalOptions>
            <additionalOption>-Xdoclint:none</additionalOption>
        </additionalOptions>
    </configuration>
</plugin>

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