Java 10+项目中如何配置maven-javadoc-plugin以正确链接旧版HTML Javadoc方法文档

刚好碰到过类似的场景，这个问题的完美解决方案是利用maven-javadoc-plugin的javadocVersion属性，它能让你为特定的<link>单独指定目标Javadoc的生成版本，从而自动适配链接格式，完全不会影响其他正常的Java 10+链接。

具体步骤 #

1. 定位到你pom.xml中maven-javadoc-plugin配置里那个指向旧版短横线格式Javadoc的<link>节点
2. 给这个<link>添加javadocVersion属性，值设为目标Javadoc实际生成时使用的Java版本（比如9、8等）

配置示例 #

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.0</version> <!-- 建议使用3.0.0及以上版本，该属性从3.0.0开始支持 -->
    <configuration>
        <!-- 其他常规配置，比如编码、输出目录等 -->
        <links>
            <!-- 指向Java 10+标准库的链接，无需特殊处理，默认生成括号格式链接 -->
            <link>https://docs.oracle.com/javase/17/docs/api/</link>
            <!-- 指向旧版Javadoc的链接，指定javadocVersion后插件会自动生成短横线格式链接 -->
            <link javadocVersion="9">https://your-old-javadoc-url/api/</link>
        </links>
    </configuration>
</plugin>

原理说明 #

maven-javadoc-plugin的javadocVersion属性会告诉插件：这个<link>指向的Javadoc是用对应版本的javadoc工具生成的。插件会根据这个版本自动切换方法链接的锚点格式：

• 当版本设为9或更低时，插件生成方法名-参数类型1-参数类型2-的短横线格式锚点，完美匹配旧版Javadoc的方法链接
• 未指定该属性时，插件默认使用当前项目的Java版本（10+），生成方法名(参数类型1,参数类型2)的括号逗号格式锚点

注意事项 #

• 必须确保你的maven-javadoc-plugin版本不低于3.0.0，因为javadocVersion属性是从这个版本才引入的
• 一定要准确设置javadocVersion的值，要和目标Javadoc生成时用的Java版本一致，否则可能还是会出现链接跳转错误的问题

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