本文详解如何通过配置 maven-javadoc-plugin 的 精确控制 Maven 站点（mvn site）中生成的 Javadoc 报告类型，实现仅生成主源码（main）Javadoc、跳过测试源码（test）Javadoc，避免因空测试类导致的构建失败。

本文详解如何通过配置 `maven-javadoc-plugin` 的 `` 精确控制 maven 站点（`mvn site`）中生成的 javadoc 报告类型，实现仅生成主源码（main）javadoc、跳过测试源码（test）javadoc，避免因空测试类导致的构建失败。

在使用 mvn site 生成项目站点时，Maven 默认会通过 maven-javadoc-plugin 自动触发 javadoc（主源码）、test-javadoc（测试源码）、aggregate 和 test-aggregate 四类报告。当项目中无 public/protected 测试类（常见于纯 @Test 方法无对应 public 类）时，test-javadoc 或 test-aggregate-no-fork 会因 No public or protected classes found to document 报错并导致 mvn site 构建失败——这正是你遇到的问题。

根本解决方式不是全局跳过 Javadoc，而是精准禁用测试相关报告，同时保留主源码文档能力。关键在于：将 maven-javadoc-plugin 的 reporting 配置显式限定为仅启用 javadoc 和 aggregate 报告，彻底排除 test-javadoc 和 test-aggregate。

✅ 正确配置方式（推荐）

在 pom.xml 的 节点下，为 maven-javadoc-plugin 明确定义 ，仅声明所需报告：

Java 接口排错助手

在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.5.0</version> <!-- 建议使用 3.4.1+，兼容 JDK 17+ -->
      <configuration>
        <encoding>UTF-8</encoding>
        <docencoding>UTF-8</docencoding>
        <charset>UTF-8</charset>
        <show>public</show>
        <windowtitle>${project.name} API Documentation</windowtitle>
      </configuration>
      <reportSets>
        <!-- 主源码 Javadoc（必需） -->
        <reportSet>
          <id>default</id>
          <reports>
            <report>javadoc</report>
            <!-- ⚠️ 注释或删除此行，禁用 test-javadoc -->
            <!-- <report>test-javadoc</report> -->
          </reports>
        </reportSet>
        <!-- 聚合模块 Javadoc（多模块项目推荐） -->
        <reportSet>
          <id>aggregate</id>
          <reports>
            <report>aggregate</report>
            <!-- ⚠️ 注释或删除此行，禁用 test-aggregate -->
            <!-- <report>test-aggregate</report> -->
          </reports>
        </reportSet>
      </reportSets>
    </plugin>

    <!-- 其他报告插件（如 maven-jxr-plugin, maven-project-info-reports-plugin）保持不变 -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jxr-plugin</artifactId>
      <version>3.3.0</version>
    </plugin>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-project-info-reports-plugin</artifactId>
      <version>3.4.3</version>
    </plugin>
  </plugins>
</reporting>

? 说明：

立即学习“Java免费学习笔记（深入）”；

• 中 仅为标识，default 对应常规单模块报告，aggregate 对应聚合报告；
• javadoc 报告生成 target/site/apidocs/（主源码），test-javadoc 生成 target/site/testapidocs/（测试源码）；
• 移除 test-javadoc 后，mvn site 将不再调用 test-javadoc-no-fork 或 test-aggregate-no-fork 目标，彻底规避空类报错。

? 验证与补充建议

• 验证是否生效：执行 mvn site -X | grep -i "test-javadoc"，输出中不应出现 test-javadoc 相关执行日志；
• 强制刷新缓存：首次修改后建议加 -U 参数更新快照依赖，并清理 target/site/ 目录再执行；
• 版本兼容性提醒：
  • maven-site-plugin 推荐 ≥ 3.12.1（最新稳定版），避免旧版 4.0.0-Mx 预发布版本的潜在兼容问题；
  • maven-javadoc-plugin ≥ 3.4.1 支持 JDK 17+ 及模块化路径，避免 javadocExecutable 手动指定（除非跨 JDK 版本构建）；
• 进阶控制（可选）：若需进一步排除特定包的 Javadoc，可在 中添加：

  <excludePackageNames>com.example.internal:com.example.test.*</excludePackageNames>

⚠️ 注意事项

• ❌ 不要使用 -Dmaven.javadoc.skip=true：该参数会全局跳过所有 Javadoc（包括主源码），违背“仅跳过 test”的需求；
• ❌ 不要依赖 true 或 ：这些属于构建生命周期参数，对 site 阶段的报告生成无效；
• ✅ 正确路径始终是 → → 的精细化声明，这是 Maven Site 插件的标准化控制机制。

通过上述配置，你将获得一个健壮、可复现的项目站点：包含完整的主源码 API 文档、源码交叉引用（Xref）、依赖分析等核心报告，而完全规避测试 Javadoc 引发的构建中断——真正实现“按需生成，精准可控”。