Apache Maven 站点插件 – 使用 maven-site-plugin 和 Maven 3

在 Maven 3 中使用 maven-site-plugin

Maven 3 中重构的一个主要目的是将 Maven 核心与Doxia分离，并允许开发任意报告系统。因此，所有与报告相关的代码都已从 Maven 3 ( MNG-4162 ) 的核心中删除。

因此，2.x 版本的 Maven 站点插件将无法与 Maven 3 一起使用。在 Maven 3 中使用此类版本的 Maven 站点插件不会从报告插件生成任何报告，只会生成手写的 Doxia 文档（apt、 xdoc, ...) 将被渲染。

您需要使用站点插件的 3.x 版本，以便它与 Maven 3 一起使用。

Maven 3 的插件兼容性矩阵
- 由 Apache Maven 社区维护的插件
- Mojo 社区维护的插件
版本分辨率
站点描述符附件
对 Maven 2 和 Maven 3 使用相同版本的 maven-site-plugin
将 maven-site-plugin 2.x 与 Maven 2 和 maven-site-plugin 3.x 与 Maven 3 一起使用
配置格式
- 经典配置（Maven 2 和 3）
- 新配置（仅限 Maven 3，不报告配置继承）
Maven 3 3.0.4 之前的报告的继承

Maven 3 的插件兼容性矩阵

由 Apache Maven 社区维护的插件

已对启用某些报告的 Maven 父 POM 的报告配置文件进行了测试。您需要更新其中一些插件才能使用 Maven 3。下面您将找到这些插件在 Maven 3 中运行所需的最低版本。

插入	版本
maven-changelog-插件	2.1
Maven 更改插件	2.1
maven-checkstyle-插件	2.5
maven-javadoc-插件	2.6.1
maven-jxr-插件	2.1
maven-插件-插件	2.5.1
maven-pmd-插件	2.4
Maven 项目信息报告插件	2.2
maven-surefire-report-plugin	2.4.3

Mojo 社区维护的插件

插入	版本
cobertura-maven-插件	2.3
emma-maven-插件	1.0-alpha-2

版本分辨率

与 Maven 3 一起使用时，报告插件版本可以为空（如构建插件）。

以下顺序/策略将用于查找/解决版本：

在 build.plugins 部分中搜索相同的 groupId/artifactId
在 build.pluginManagement.plugins 部分中搜索相同的 groupId/artifactId
使用当前存储库解析（可以包括自动 SNAPSHOT 解析）

请注意，如果报告插件版本为空，Maven 3.0.x 会报告误导性警告：请参阅MNG-5477，已在 Maven 3.1.0 中修复。

站点描述符附件

在 Maven 3 中， site:attach-descriptor的默认执行已从pom打包项目的内置生命周期绑定中删除。实际使用这些项目为子模块提供公共站点描述符的用户将需要明确定义以下目标执行以恢复预期行为：

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-site-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-descriptor</id>
            <goals>
              <goal>attach-descriptor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

对 Maven 2 和 Maven 3 使用相同版本的 maven-site-plugin

从 3.0 版开始，maven-site-plugin 可以与 Maven 2.2.x 和 3.x 一起运行。如果在<reporting>部分中以经典的 Maven 2 方式配置报告，结果应该完全相同。如果您使用新的 Maven 3 配置报告的方式（不推荐），在<reportPlugins>部分，它将仅适用于 Maven 3。

以下代码片段在使用 Maven 3 运行时会自动激活site:attach-descriptor ：

  <profiles>
    <profile>
      <id>maven-3</id>
      <activation>
        <file>
          <!--  This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
          <exists>${basedir}</exists>
        </file>
      </activation>
      <build>
        <plugins>
          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-descriptor</id>
                <goals>
                  <goal>attach-descriptor</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

注意：由于 POM 默认生命周期映射，需要配置文件以避免在使用 Maven 2.2.x 运行时重复安装和部署站点描述符。

将 maven-site-plugin 2.x 与 Maven 2 和 maven-site-plugin 3.x 与 Maven 3 一起使用

在 maven-site-plugin 3.0 之前，maven-site-plugin 2.x 仅与 Maven 2 兼容，maven-site-plugin 3.0-betas 仅与 Maven 3 兼容。需要一个技巧来让 Maven 2 使用一个版本的该插件和 Maven 3 在同一个pom.xml中的另一个版本。

以下代码片段在使用 Maven 3 运行时会自动激活 maven-site-plugin 3.x：

  <profiles>
    <profile>
      <id>maven-3</id>
      <activation>
        <file>
          <!--  This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
          <exists>${basedir}</exists>
        </file>
      </activation>
      <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-site-plugin</artifactId>
              <version>3.9.0</version>
            </plugin>
          </plugins>
        </pluginManagement>
        <plugins>
          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-descriptor</id>
                <goals>
                  <goal>attach-descriptor</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

注意：请注意，您还应该使用<pluginManagement>来指定 maven-site-plugin 2.x 的版本。如果您直接在<build>元素的<plugins>部分中定义插件版本，则始终使用该版本，无论使用哪个版本的 Maven。该片段看起来像这样：

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-site-plugin</artifactId>
          <version>2.3</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>

配置格式

POM的<reporting>部分已作为Maven 3 中的<reportPlugins>添加到站点插件的配置中。配置的内容已尽可能与 Maven 2 相似，并且maven-reporting-exec组件转换配置在飞行中。

经典配置（Maven 2 和 3）

报告在 POM 的<reporting>部分中配置。这仍然是推荐的配置格式。

<project>
...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.4</version>
        <configuration>
          <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
          <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
        </configuration>
        <reportSets>
          <reportSet>
            <reports>
              <report>dependencies</report>
              <report>scm</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.8</version>
      </plugin>
    </plugins>
  </reporting>
...
</project>

新配置（仅限 Maven 3，不报告配置继承）

从maven-site-plugin 3.0 开始，报告可以在maven-site-plugin的配置中配置为<reportPlugins>元素。

这种新的配置格式实际上并没有为最终用户准备好：请暂时不要使用它。

因此，使用maven-site-plugin 3.7，<reportPlugins>配置已被简单地删除（并从 3.3 开始标记为私有/内部），如果使用 <reportPlugins> ， Maven 3.5.0 会打印以下警告：

[WARNING] Reporting configuration should be done in <reporting> section, not in maven-site-plugin <configuration> as reportPlugins parameter.

本文档公开只是为了帮助在以前版本中使用<reportPlugins>的人了解他们为什么需要迁移回经典配置，并了解如何切换回<reports><plugins>经典配置。

说明：（以前的）新格式不支持报告插件配置继承，这对可用性至关重要：参见MSITE-484。该字段在技术上是从 Maven 3 中删除大多数报告逻辑所必需的，但仍需要添加新的继承机制以使其与旧格式一样灵活：我们在发现此关键限制之前公开了该字段，并需要稍后解释原因最终用户不能使用它，然后不能使用它，因为maven-site-plugin 3.3。

以下是此功能的外观：

<project>
...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.2</version><!-- last maven-site-plugin version supporting this reportPlugins configuration -->
        <configuration>
          ...
          <reportPlugins><!-- not supported any more, causes WARNING in Maven 3.5.0: move to <project><reporting><plugins> instead -->
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-project-info-reports-plugin</artifactId>
              <version>2.4</version>
              <configuration>
                <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
                <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
              </configuration>
              <!-- simpler configuration without reportSets available for usual cases -->
              <reports>
                <report>dependencies</report>
                <report>scm</report>
              </reports>
            </plugin>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <version>2.8</version>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
...
</project>

Maven 3 3.0.4 之前的报告的继承

在处理报告的继承时，3.0.4 之前的 Maven 3 与 Maven 2 的工作方式不同：给定一个提供多个报告目标的插件，在 Maven 2 中，在子 pom 中配置的报告被添加到来自父级的报告中，而在 Maven 3 中直到 3.0。来自孩子的 3 份报告替换来自父母的报告。但是，从 3.0.4 开始，报告继承的工作方式与 Maven 2 相同。

例如，给定一个多模块构建，其中父 POM 配置了索引报告，子 POM配置了为maven-project-info-reports-plugin插件配置的摘要报告：

使用 Maven 2 和 Maven 3.0.4，子站点将同时具有索引和摘要报告，
使用 Maven 3.0.3，子站点将只有摘要报告。

有关详细信息，请参阅MSITE-596。