Maven Plugin

文档

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

default-bindings-plugins

https://maven.apache.org/ref/3.8.5/maven-core/default-bindings.html

maven-archiver

https://maven.apache.org/shared/maven-archiver/index.html

The Maven Archiver is mainly used by plugins to handle packaging. The version numbers referenced in the Since column on this page are the version of the Maven Archiver component - not for any specific plugin. To see which version of Maven Archiver a plugin uses, go to the site for that plugin.

<archive>
  <addMavenDescriptor/>
  <compress/>
  <forced/>
  <index/>
  <pomPropertiesFile/>
 
  <manifestFile/>
  <manifest>
    <addClasspath/>
    <addDefaultEntries/>
    <addDefaultImplementationEntries/>
    <addDefaultSpecificationEntries/>
    <addBuildEnvironmentEntries/>
    <addExtensions/>
    <classpathLayoutType/>
    <classpathPrefix/>
    <customClasspathLayout/>
    <mainClass/>
    <packageName/>
    <useUniqueVersions/>
  </manifest>
  <manifestEntries>
    <key>value</key>
  </manifestEntries>
  <manifestSections>
    <manifestSection>
      <name/>
      <manifestEntries>
        <key>value</key>
      </manifestEntries>
    <manifestSection/>
  </manifestSections>
</archive>

manifest

https://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html

Customization the Manifest

The default manifest can be altered with the archive configuration element. Below you will find some of the configuration options that are available. For more info see the Maven Archiver reference.

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.3.0</version>
        <configuration>
          <archive>
            <index>true</index>
            <manifest>
              <addClasspath>true</addClasspath>
            </manifest>
            <manifestEntries>
              <mode>development</mode>
              <url>${project.url}</url>
              <key>value</key>
            </manifestEntries>
          </archive>
        </configuration>
        ...
      </plugin>
    </plugins>
  </build>
  ...
</project>

Manifest Entries

https://maven.apache.org/shared/maven-archiver/examples/manifestEntries.html

If you find that the other configuration options for Maven Archiver are not enough for manipulating the manifest, you can add your own entries to it. This is done with the <manifestEntries> configuration element.

In this example we'll add some entries to the manifest by specifying what we'd like in the <configuration>/<archive> element of maven-jar-plugin.

Note: As with all the examples here, this configuration can be used in all plugins that use Maven Archiver, not just maven-jar-plugin as in this example.

<project>
  <url>http://some.url.org/</url>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        ...
        <configuration>
          <archive>
            <manifestEntries>
              <mode>development</mode>
              <url>${project.url}</url>
            </manifestEntries>
          </archive>
        </configuration>
        ...
      </plugin>
    </plugins>
  </build>
  ...
</project>

As you see above you can use literal values or you can have values from the POM interpolated into literals or simply use straight POM expressions. So this is what your resultant manifest will look like inside the created jar:

Manifest-Version: 1.0
Created-By: Apache Maven ${maven.version}
Build-Jdk: ${java.version}
mode: development
url: http://some.url.org/

maven-jar-plugin

https://maven.apache.org/plugins/maven-jar-plugin/

This plugin provides the capability to build jars. To sign jars, use the Maven Jarsigner Plugin.

usage

https://maven.apache.org/plugins/maven-jar-plugin/usage.html

How to build a JAR file

When you want to create a JAR-file with Maven, you first have to create a pom.xml-file with at least the following content:

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

Since 'jar' is the default packaging type it is not required to set it in this case. Apart from the above you will normally want some real java source files which should be located within src/main/java.

If you need extra resources on your classpath (for example property files) they should be located in src/main/resources.

Now we can create a JAR-file by using the command below:

mvn package

The 'package' phase is always responsible for bundling all the files in the artifact, in this case a JAR-file.

In your project's target directory you'll see the generated jar file which is named like: 'core-1.0-SNAPSHOT.jar'. The resulting 'jar' file contains the compiled java class files as well as the files from src/main/resources.

Usually there is no need to mentioned the 'maven-jar-plugin' explicit cause it's bound to the Maven Build Life Cycle.

For full documentation, click here.

https://maven.apache.org/plugins/maven-jar-plugin/plugin-info.html

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jar-plugin</artifactId>
          <version>3.3.0</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.3.0</version>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

include/exclude content

https://maven.apache.org/plugins/maven-jar-plugin/examples/include-exclude.html

Specify a list of fileset patterns to be included or excluded by adding <includes>/<include> or <excludes>/<exclude> in your pom.xml.

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.3.0</version>
        <configuration>
          <includes>
            <include>**/service/*</include>
          </includes>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Make The Jar Executable

https://maven.apache.org/shared/maven-archiver/examples/classpath.html#Make

If you want to create an executable jar file, you need to configure Maven Archiver accordingly. You need to tell it which main class to use. This is done with the <mainClass> configuration element. Here is a sample pom.xml configured to add the classpath and use the class fully.qualified.MainClass as the main class:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        ...
        <configuration>
          <archive>
            <manifest>
              <addClasspath>true</addClasspath>
              <mainClass>fully.qualified.MainClass</mainClass>
            </manifest>
          </archive>
        </configuration>
        ...
      </plugin>
    </plugins>
  </build>
  ...
  <dependencies>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.1</version>
    </dependency>
    <dependency>
      <groupId>org.codehaus.plexus</groupId>
      <artifactId>plexus-utils</artifactId>
      <version>1.1</version>
    </dependency>
  </dependencies>
  ...
</project>

The manifest produced using the above configuration would look like this:

Manifest-Version: 1.0
Created-By: Apache Maven ${maven.version}
Build-Jdk: ${java.version}
Main-Class: fully.qualified.MainClass
Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar

maven-compiler-plugin

https://maven.apache.org/plugins/maven-compiler-plugin/

source & target

https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html

Sometimes when you may need to compile a certain project to a different version than what you are currently using. The javac can accept such command using -source and -target. The Compiler Plugin can also be configured to provide these options during compilation.

For example, if you want to use the Java 8 language features (-source 1.8) and also want the compiled classes to be compatible with JVM 1.8 (-target 1.8), you can either add the two following properties, which are the default property names for the plugin parameters:

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

or configure the plugin directly:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.10.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>
    </plugins>
    [...]
  </build>
  [...]
</project>

再看一个示例

<plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>

Usage

Configuring Your Compiler Plugin

Since the Compiler Plugin executes automatically during their phases, you don't have to put executions unlike many other plugins. However, you should specify the version of the Compiler Plugin.

<project>
  ...
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.10.1</version>
          <configuration>
            <!-- put your configurations here -->
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  ...
</project>

release

Starting JDK 9, the javac executable can accept the --release option to specify against which Java SE release you want to build the project. For example, you have JDK 11 installed and used by Maven, but you want to build the project against Java 8. The --release option ensures that the code is compiled following the rules of the programming language of the specified release, and that generated classes target the release as well as the public API of that release. This means that, unlike the -source and -target options, the compiler will detect and generate an error when using APIs that don't exist in previous releases of Java SE.

Since version 3.6 of the Compiler Plugin, this option can be provided either via a property:

<project>
  [...]
  <properties>
    <maven.compiler.release>8</maven.compiler.release>
  </properties>
  [...]
</project>

or by configuring the plugin directly:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.10.1</version>
        <configuration>
          <release>8</release>
        </configuration>
      </plugin>
    </plugins>
    [...]
  </build>
  [...]
</project>

maven-resources-plugin

refer to : https://maven.apache.org/plugins/maven-resources-plugin/index.html

The Resources Plugin handles the copying of project resources to the output directory.

There are two different kinds of resources: main resources and test resources.

The difference is that the main resources are the resources associated to the main source code while the test resources are associated to the test source code.

Specifying a character encoding scheme

refer to : https://maven.apache.org/plugins/maven-resources-plugin/examples/encoding.html

A character encoding scheme such as ASCII, UTF-8 or UTF-16 can be chosen to be used for the reading and writing of files.

The best practice is to define encoding for copying filtered resources via the property ${project.build.sourceEncoding} which should be defined in the pom properties section like this:

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

By using the above property maven-resources-plugin will automatically use this encoding.

Filtering

refer to : https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html

Variables can be included in your resources. These variables, denoted by the ${...} or @...@ delimiters, can come from the system properties, your project properties, from your filter resources and from the command line.

For example, if we have a resource src/main/resources/hello.txt containing

Hello ${name}

And a POM like this

<project>  ...  <name>My Resources Plugin Practice Project</name>  ...  <build>    ...    <resources>      <resource>        <directory>src/main/resources</directory>      </resource>      ...    </resources>    ...  </build>  ...</project>

Upon calling

mvn resources:resources

This will create a resource output in target/classes/hello.txt which contains exactly the same text.

Hello ${name}

However, if we add a <filtering> tag to our POM and set it to true like this:

<project>      ...      <resource>        <directory>src/main/resources</directory>        <filtering>true</filtering>      </resource>      ...</project>

Our target/classes/hello.txt after calling

mvn resources:resources

would be

Hello My Resources Plugin Practice Project

That's because the name variable was replaced by the value of the project's name (which was specified in the POM).

filter & include & exclude

我们来看一段spring-boot-starter-parent中配置：

<build>
    <resources>
      <resource>
        <directory>${basedir}/src/main/resources</directory>
        <filtering>true</filtering>
        <includes>
          <include>**/application*.yml</include>
          <include>**/application*.yaml</include>
          <include>**/application*.properties</include>
        </includes>
      </resource>
      <resource>
        <directory>${basedir}/src/main/resources</directory>
        <excludes>
          <exclude>**/application*.yml</exclude>
          <exclude>**/application*.yaml</exclude>
          <exclude>**/application*.properties</exclude>
        </excludes>
      </resource>
    </resources>
</build>  
  

上面的这段配置，含义是：对于 ${basedir}/src/main/resources下，**/application*.yml,**/application*.yaml,**/application*.properties这些文件内的占位符，全部进行替换（filtering=true），而对于 ${basedir}/src/main/resources下，排除了 **/application*.yml,**/application*.yaml,**/application*.properties后，其他的文件内的占位符，不进行替换。

maven-source-plugin

https://maven.apache.org/plugins/maven-source-plugin/

示例：

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

source:jar 和 source:jar-no-fork的区别：

以下是 maven-source-plugin 中 source:jar-no-fork 和 source:jar 的核心区别及使用建议：

---

1. 核心区别

特性	**source:jar-no-fork**	**source:jar**
构建进程	不启动新 JVM 进程，直接在当前 Maven 进程中执行打包	启动新 JVM 进程（fork 模式），独立执行打包
构建效率	✅ 更高（避免进程创建开销）	⚠️ 较低（进程切换消耗资源）
生命周期绑定	需显式绑定到生命周期阶段（如 package或 verify）	默认绑定到 package阶段
适用场景	推荐用于标准构建流程（避免重复打包）	适用于需要隔离环境的场景（如自定义编译参数）

---

2. 配置差异

**source:jar-no-fork 示例配置（避免重复打包）**

xml
复制
<plugin>
    <groupId>org.apache.maven.pluginsgroupId>
    <artifactId>maven-source-pluginartifactId>
    <version>3.3.1version>
    <executions>
        <execution>
            <id>attach-sourcesid>
            <phase>packagephase>
            <goals>
                <goal>jar-no-forkgoal> 
            goals>
        execution>
    executions>
plugin>

作用：在 package 阶段直接打包源码，不触发额外进程，避免因重复执行导致部署失败。

**source:jar 的潜在问题**

若配置为 <goal>jar</goal> 且 Maven ≥ 3.5，可能因默认行为触发 jar-no-fork 和 jar 两个目标，导致源码包被重复生成和部署，引发 Nexus 仓库拒绝接收。

---

3. 使用建议

1. 优先使用 jar-no-fork：
   在 Maven 3.5+ 版本中，始终使用 jar-no-fork 以避免重复打包问题。
2. 清理冗余配置：
   检查是否同时存在多个 <execution> 配置，删除重复或冲突的 source:jar 目标。
3. 绑定阶段选择：
   推荐绑定到 package 或 verify 阶段（如上述配置），确保在构建主包后生成源码包。
4. 多模块项目注意：
   需在子模块的 POM 中单独配置，顶层 POM 的配置可能不生效。

---

常见问题

Q：为何部署到 Nexus 时提示 "重复部署源码包"？
A：通常因同时执行了 source:jar 和 source:jar-no-fork。解决方案：

• 将所有 <goal>jar</goal> 改为 <goal>jar-no-fork</goal>；
• 删除多余的 <execution> 配置。

Q：是否必须显式绑定生命周期？
A：source:jar 默认绑定到 package，但 jar-no-fork 需手动绑定（如不绑定，需通过命令 mvn source:jar-no-fork 单独执行）。

---

通过上述配置优化，可避免源码包重复生成问题，提升构建效率与稳定性 ✅。

maven-javadoc-plugin

https://maven.apache.org/plugins/maven-javadoc-plugin/

示例：

<plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <!-- 禁用严格语法检测 -->
                    <doclint>none</doclint>
                    <failOnError>false</failOnError>
                </configuration>
            </plugin>

• javadoc:jar creates an archive file of the generated Javadocs. It is used during the release process to create the Javadoc artifact for the project's release. This artifact is uploaded to the remote repository along with the project's compiled binary and source archive.

https://maven.apache.org/plugins/maven-javadoc-plugin/jar-mojo.html

针对javadoc:jar 这个goal，有以下几个常用的configuration:

Specifies specific checks to be performed on Javadoc comments.
See also: Additional Doclet option Xdoclint.

• Type: java.lang.String
• Since: 3.0.0
• Required: No
• User Property: doclint

Specifies if the build will fail if there are errors during javadoc execution or not.

• Type: boolean
• Since: 2.5
• Required: No
• User Property: maven.javadoc.failOnError
• Default: true