Maven构建site时javadoc生成失败 找不到provided依赖如何解决

问题根因 #

Maven 官方的 maven-javadoc-plugin 默认仅将 compile、runtime 范围的依赖纳入 javadoc 生成的类路径，你项目中使用的 io.papermc.paper:paper-api 属于 provided 范围，默认不会被加载，因此 javadoc 无法解析相关类导致报错。
IntelliJ 运行 Maven 命令时会默认把项目所有范围的依赖都加载到运行上下文的类路径中，因此不会触发报错，和纯命令行的 Maven 执行规则存在差异。

解决方案 #

方案1：全局纳入provided范围依赖 #

直接调整 maven-javadoc-plugin 配置，将 provided 加入类路径扫描范围，示例配置如下：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.3</version> <!-- 建议使用最新稳定版 -->
  <configuration>
    <!-- 新增该行，将provided加入javadoc的依赖扫描范围 -->
    <includeDependencyScopes>compile, runtime, provided</includeDependencyScopes>
    <failOnError>true</failOnError>
    <failOnWarning>false</failOnWarning>
  </configuration>
</plugin>

方案2：仅添加必要的API依赖 #

如果你不想把所有 provided 范围的依赖都纳入类路径，可以单独指定需要的 Paper API 作为 javadoc 额外依赖：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.3</version>
  <configuration>
    <additionalDependencies>
      <additionalDependency>
        <groupId>io.papermc.paper</groupId>
        <artifactId>paper-api</artifactId>
        <version>填写你项目实际使用的paper-api版本</version>
      </additionalDependency>
    </additionalDependencies>
    <failOnError>true</failOnError>
    <failOnWarning>false</failOnWarning>
  </configuration>
</plugin>

注：如果之前配置additionalDependencies无效，可检查是否版本、坐标和项目依赖的paper-api完全一致。

验证配置 #

配置完成后先执行 mvn clean javadoc:javadoc 单独测试 javadoc 生成环节，确认无报错后再执行 mvn clean site 即可。

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