Maven 插件

Maven Plugins

Ynthm Wang 收录于开发工具

2022-10-15 约 3823 字预计阅读 8 分钟

Maven 本质上是一个插件执行框架；所有工作都由插件完成。

寻找要执行的特定目标？此页面列出了核心插件和其他。有构建和报告插件：

构建插件 将在构建期间执行，它们应该在 POM 的 <build/> 元素中配置。
报告插件 将在站点生成期间执行，它们应在 POM 的 <reporting/> 元素中进行配置。因为报告插件的结果是生成网站的一部分，所以报告插件应该是国际化和本地化的。

Maven 项目支持的插件 Core plugins

Apache Maven Clean Plugin

编译后清理。

1
2
3
4
5
6


# the first clean refers to the plugin's alias, and the second clean refers to the plugin goal.
mvn clean:clean
# 但是，Clean Plugin 是一个特殊的插件，并且绑定到它自己的特殊生命周期阶段，称为 clean. 因此，为简单起见，也可以使用以下命令执行
mvn clean
# 或其他阶段/目标(phases/goals)
mvn clean package site

发现并清楚配置的以下路径

project.build.directory
project.build.outputDirectory
project.build.testOutputDirectory
project.reporting.outputDirectory

每次构建项目时运行 Clean Plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <id>auto-clean</id>
            <phase>initialize</phase>
            <goals>
              <goal>clean</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Apache Maven Compiler Plugin

编译 Java 源代码。

Setting the -source and -target of the Java Compiler

The javac can accept such command using -source and -target. The Compiler Plugin can also be configured to provide these options during compilation.

1
2
3
4
5
6
7
8


<project>
  [...]
  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  [...]
</project>

或者

1
2
3
4
5
6
7
8


<project>
  [...]
  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  [...]
</project>

1
2
3
4


# 编译源码
mvn compile
# 编译测试源码
mvn test-compile

Apache Maven Install Plugin

在此阶段使用 Install Plugin install 将工件添加到本地存储库。安装插件使用 POM 中的信息（groupId、artifactId、version）来确定工件在本地存储库中的正确位置。

可使用 ~/.m2/settings.xml 中 <localRepository> 元素配置该位置。

Apache Maven 有一个两级策略来解析和分发文件，我们称之为工件。第一级称为local repository，它是系统上的工件缓存，默认位于 ${user.home}/.m2/repository. 执行 Maven 时，它首先在此本地缓存中查找工件。如果在此处找不到工件，Maven 将访问远程存储库以查找工件。一旦找到，它将被存储到本地存储库中，因此可供当前和将来使用。

使用 maven-install-plugin 可以将您的工件放在本地存储库中。要将工件上传到远程存储库，您需要使用 maven-deploy-plugin。

1

mvn install

只 deploy 某些模块

1
2


mvn clean deploy -F -am
mvn clean deploy -pl module-a -am

不需要 install 与 deploy

1
2
3
4


<properties>
  <maven.deploy.skip>true</maven.deploy.skip>
  <maven.install.skip>true</maven.install.skip>
</properties>

或者

1
2
3
4
5
6
7
8


<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-deploy-plugin</artifactId>
    <version>${deploy-plugin.version}</version>
    <configuration>
      <skip>true</skip>
    </configuration>
</plugin>

Apache Maven Deploy Plugin

部署插件主要用于部署阶段，将您的工件添加到远程存储库，以便与其他开发人员和项目共享。这通常在集成或发布环境中完成。它还可以用于部署特定的工件。

deploy:deploy

POM 必须包含一个有效的 <distributionManagement/> 部分，它至少<repository/> 为您的工件提供定义远程存储库位置。要将快照工件与发布工件分开，您还可以指定一个 <snapshotRepository/> 位置。最后，要部署项目网站，您还必须 <site/> 在此处指定一个部分。还需要注意的是，此部分可以继承，允许您为一组相关项目指定一次部署位置。

1
2
3
4
5
6
7
8
9


[...]
  <distributionManagement>
    <repository>
      <id>internal.repo</id>
      <name>MyCo Internal Repository</name>
      <url>Host to Company Repository</url>
    </repository>
  </distributionManagement>
[...]

如果您的存储库是安全的，您可能还需要配置settings.xml文件以定义 <server/> 提供身份验证信息的相应条目。

服务器条目使用它们的 <id/> 元素匹配到 POM 中 distributionManagement 的不同部分。

1
2
3
4
5
6
7


[...]
    <server>
      <id>internal.repo</id>
      <username>maven</username>
      <password>foobar</password>
    </server>
[...]

1

mvn deploy

Apache Maven Resources Plugin

默认项目资源路径，可配置，可多路径。

src/main/resources
src/test/resources

目标概述

资源插件将资源元素指定的文件复制到输出目录。以下三种变体仅在指定或默认资源和输出目录元素的方式上有所不同。资源插件有三个目标：

resources:resources 将主源代码的资源复制到主输出目录。这个目标通常会自动执行，因为它默认绑定到 process-resources 生命周期阶段。它总是使用 project.build.resources 元素来指定资源，并且默认使用 project.build.outputDirectory 来指定复制目标。
resources:testResources 将测试源代码的资源复制到测试输出目录。这个目标通常会自动执行，因为它默认绑定到 process-test-resources 生命周期阶段。它总是使用 project.build.testResources 元素来指定资源，并且默认使用 project.build.testOutputDirectory 来指定复制目标。
resources:copy-resources 将资源复制到输出目录。此目标要求您配置要复制的资源，并指定 outputDirectory。

Including and excluding files and directories

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


<project ...>
 ...
 <properties>
   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   ...
 </properties>
 ..
</project>

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.3.0</version>
        <configuration>
          ...
          <encoding>UTF-8</encoding>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

Maven Surefire Plugin

Surefire 插件在 test 构建生命周期阶段用于执行应用程序的单元测试。它以两种不同的文件格式生成报告：

纯文本文件 ( *.txt)
XML 文件 ( *.xml)

默认情况下，这些文件在 ${basedir}/target/surefire-reports/TEST-*.xml.

有关报告的 HTML 格式，请参阅 Maven Surefire Report Plugin

Best practice is to define the version of the Surefire Plugin that you want to use in either your pom.xml or a parent pom.xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-surefire-plugin</artifactId>
          <version>3.0.0-M7</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>

1

mvn test

Skipping Tests

1
2
3


mvn install -DskipTests
# skip compiling the tests. maven.test.skip is honored by Surefire, Failsafe and the Compiler Plugin.
mvn install -Dmaven.test.skip=true

Maven Surefire Report Plugin

Generate the Report as Part of Project Reports

To generate the Surefire report as part of the site generation, add the following in the <reporting> section of your POM:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>3.0.0-M7</version>
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

Maven Failsafe Plugin

Failsafe 插件旨在运行集成测试，而 Surefire 插件旨在运行单元测试。选择名称 (failsafe) 既是因为它是万能的同义词，也是因为它暗示当它失败时，它会以一种安全的方式进行。

有关报告的 HTML 格式，请参阅 Maven Surefire Report Plugin

Maven 生命周期有四个运行集成测试的阶段：

pre-integration-test 用于设置集成测试环境。
integration-test 用于运行集成测试。
post-integration-test 用于拆除集成测试环境。
verify 用于检查集成测试的结果。

Failsafe 插件只有两个目标：

failsafe:integration-test 运行应用程序的集成测试。
failsafe:verify 验证应用程序的集成测试是否通过。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>3.0.0-M7</version>
        <executions>
          <execution>
            <goals>
              <goal>integration-test</goal>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

1

mvn verify

Usage in multi-module projects

parent pom.xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-failsafe-plugin</artifactId>
          <version>3.0.0-M7</version>
          <executions>
            <execution>
              <id>integration-test</id>
              <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>

The child projects can then trigger usage of the Failsafe Plugin with

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>3.0.0-M7</version>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

对于非常复杂的构建，最好将integration-test和verify目标的执行分开。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-failsafe-plugin</artifactId>
          <version>3.0.0-M7</version>
          <executions>
            <execution>
              <id>integration-test</id>
              <goals>
                <goal>integration-test</goal>
              </goals>
            </execution>
            <execution>
              <id>verify</id>
              <goals>
                <goal>verify</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>

Packaging types/tools

Apache Maven JAR Plugin

这个插件提供了构建 jars 的能力。要对 jars 签名，请使用 Maven Jarsigner Plugin。

1
2
3
4
5
6
7
8


<project>
  <modelVersion>4.0.0</modelVersion>
  
  <groupId>com.mycompany.project</groupId>
  <artifactId>core</artifactId>
  <version>1.0-SNAPSHOT</version>
  <!-- <packaging>jar</packaging>  -->
</project>

通常不需要明确提及“maven-jar-plugin”，因为它绑定到 Maven Build Life Cycle。

1

mvn package

Apache Maven Shade Plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.4.0</version>
        <configuration>
          <!-- put your configurations here -->
        </configuration>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

1

mvn package

Executable JAR

Apache Maven Source Plugin

创建当前项目源文件的 jar 存档。默认情况下，jar 文件是在项目的目标目录中创建的。

1
2


mvn source:jar
mvn source:test-jar

Installing the sources using a phase binding

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>3.2.1</version>
        <executions>
          <execution>
            <id>attach-sources</id>
            <phase>package</phase>
            <goals>
              <goal>jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

执行 mvn install，maven 会自动将 source install 到 repository
执行 mvn deploy，maven 会自动将 source deploy 到 remote-repository

注意：在多项目构建中，将插件置于顶层或 parent 的 pom 中并不会发挥作用，必须置于具体项目的 pom 中。

Reporting plugins

Apache Maven Checkstyle Plugin

Checkstyle 插件生成有关开发人员使用的代码样式的报告。有关 Checkstyle 的更多信息，请参阅 https://checkstyle.org/

该插件可以在项目的 POM 中配置。可用于此版本插件的预定义规则集是：sun_checks.xml 和 google_checks.xml. 您还可以通过在插件配置中指定自定义规则集来使用它。

Generate Checkstyle Report As Part of the Project Reports

A custom Checker configuration xml file can be defined and then referenced via a URL, File, or build classpath resource reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


<project>
  ...
   <reporting>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-checkstyle-plugin</artifactId>
          <version>3.2.0</version>
          <configuration>
            <configLocation>checkstyle.xml</configLocation>
          </configuration>
          <reportSets>
            <reportSet>
              <reports>
                <report>checkstyle</report>
              </reports>
            </reportSet>
          </reportSets>
        </plugin>
      </plugins>
    </reporting>
  ...
</project>

1
2
3
4


# execute the site phase to generate the report.
mvn site
# Generate Checkstyle Report As Standalone
mvn checkstyle:checkstyle

Checking for Violations as Part of the Build

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-checkstyle-plugin</artifactId>
   <version>3.2.0</version>
   <configuration>
      <!-- reference : https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml -->
     <configLocation>google_checks.xml</configLocation>
     <encoding>UTF-8</encoding>
     <consoleOutput>true</consoleOutput>
     <failsOnError>true</failsOnError>
     <linkXRef>false</linkXRef>
  </configuration>
  <executions>
     <execution>
       <id>validate</id>
       <phase>validate</phase>
       <goals>
         <goal>check</goal>
       </goals>
     </execution>
  </executions>
</plugin>

Multimodule Configuration

Apache Maven Javadoc Plugin

插件使用 Javadoc 工具为指定项目生成 javadocs。

Generate Javadocs As Part Of Project Reports

When you execute mvn site, the javadocs will be generated and included in the generated site. A link to the javadocs will be added in the Project Reports menu.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.4.1</version>
        <configuration>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </reporting>
  ...
</project>

Generate Standalone Javadocs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.4.1</version>
        <configuration>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

1

mvn javadoc:javadoc

Aggregating Javadocs For Multi-Projects

Tools

Apache Maven Dependency Plugin

1
2
3


dependency:analyze
dependency:copy-dependencies
dependency:tree -DoutputFile=/path/to/file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.3.0</version>
        <executions>
          <execution>
            <id>copy-dependencies</id>
            <phase>package</phase>
            <goals>
              <goal>copy-dependencies</goal>
            </goals>
            <configuration>
              <!-- configure the plugin here -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Usage

Maven Release Plugin

本插件用于用Maven发布项目，省去了很多重复的、手工的工作。发布项目分为两个步骤：prepare 和 perform 。

目标概述:

release:clean 在发布准备后清理。
release:prepare 准备在 SCM 中发布。
release:prepare-with-pom 在 SCM 中准备发布，并生成发布 POM，记录使用的完全解决的项目。
release:rollback 回滚以前的版本。
release:perform 从 SCM 执行发布。
release:stage 执行从 SCM 到暂存文件夹/存储库的发布。
release:branch 创建当前项目的分支并更新所有版本。
release:update-versions 更新 POM(s) 中的版本。

用法

scm 部分带有 developerConnection
带有锁定版本的 maven-release-plugin

developerConnection 包含指向包含pom.xml此 URL 的文件夹的源代码控制管理系统的 URL，因此 scm:[scm-provider] 插件可以选择正确的实现来提交和标记。Maven SCM-page 包含所有受支持的SCM 的概述，每个 SCM 你可以看到 URL 的样子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<project>
  ...
  <scm>
    <developerConnection>scm:git:https://github.com/my-org/my-project.git</developerConnection>
  </scm>
  
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>3.0.0-M6</version>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

Do a Dry Run:

由于发布插件执行了许多更改项目的操作，因此在大发布之前或在新项目上进行试运行可能是明智的。为此，提交所有文件，就像您即将运行完整版本并运行

1

mvn release:prepare -DdryRun

这将询问所有相同的问题，运行相同的测试，并输出 POM 在转换后的外观副本。您可以检查输出并查看 POM（带有.tag和.next后缀），然后运行

1

mvn release:perform -DdryRun

这将显示执行操作然后清理项目，即。删除上面创建的所有文件，项目将准备好执行正确的发布。

以批处理模式运行:

有时需要定期执行提交/标记过程（例如，通过构建服务器生成夜间或集成构建）。要使用版本和标签信息的默认输入而不提示任何值，请使用 Maven 的–batch-mode设置：

1

mvn --batch-mode release:prepare

1
2
3


mvn release:update-versions
mvn release:update-versions -DautoVersionSubmodules=true
mvn --batch-mode release:update-versions -DdevelopmentVersion=1.2.0-SNAPSHOT

Apache Maven Assembly Plugin

Maven 的组装插件使开发人员能够将项目输出组合到一个可分发的存档中，该存档还包含依赖项、模块、站点文档和其他文件。

To use the Assembly Plugin in Maven, you simply need to:

choose or write the assembly descriptor to use,
configure the Assembly Plugin in your project’s pom.xml, and
run “mvn assembly:single” on your project.

To write your own custom assembly, you will need to refer to the Assembly Descriptor Format reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <!-- NOTE: We don't need a groupId specification because the group is
             org.apache.maven.plugins ...which is assumed by default.
         -->
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.4.2</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
        [...]
</project>

Usage

Maven Enforcer Plugin

Enforcer 插件提供了控制某些环境约束的目标，例如 Maven 版本、JDK 版本和 OS 系列以及更多内置规则和用户创建的规则。

附录

https://maven.apache.org/plugins/index.html