使用maven-javadoc-plugin生成Javadoc时出现String index out of range错误

原因分析 #

• 这个报错是Oracle JDK 8自带javadoc工具的已知底层bug，触发条件是：javadoc扫描classpath时加载到了Java 6及更低版本编译的、和当前项目同包名的类，解析低版本字节码的常量池时计算索引错误，直接抛出未捕获的StringIndexOutOfBoundsException。因为异常抛在最底层的字节码解析逻辑，上层没有做上下文日志埋点，所以不会输出具体是哪个类触发的问题。
• 你提到的「项目包名和依赖内包名完全一致」就是核心触发条件：如果包名不同，javadoc处理当前项目代码时不会主动加载外部依赖的类结构做上下文解析；只有同包名时，javadoc会把依赖内的同包类纳入当前项目的上下文处理，刚好碰到不兼容的低版本字节码就触发崩溃。

解决方案 #

下面三个方案按优先级选择即可：

方案1：插件配置排除问题依赖（最推荐） #

直接在maven-javadoc-plugin的配置中添加依赖排除规则，插件会自动把该依赖从javadoc的classpath中移除，无需手动修改options文件，配置示例如下：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.2.0</version>
    <configuration>
        <!-- 替换为你出问题的依赖的groupId:artifactId -->
        <dependencyExcludes>com.yourcompany:your-private-sdk</dependencyExcludes>
    </configuration>
</plugin>

方案2：统一依赖的字节码版本 #

如果需要保留该依赖在javadoc的上下文中，可将该依赖用Java 8及以上版本重新编译后，再执行mvn install:install-file安装到本地仓库，字节码版本兼容后就不会触发解析错误。

方案3：升级javadoc工具版本 #

如果无法修改依赖，也可以用JDK 9及以上版本的javadoc工具生成文档，该解析bug在JDK 9之后已经被修复，无需修改项目代码和配置，只需要在执行mvn命令时指定javadoc路径即可：

mvn javadoc:javadoc -Djavadoc.executable=/path/to/jdk-11/bin/javadoc

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