Maven 核心插件 maven-clean-plugin 使用详解

在软件开发中，构建和管理项目的复杂性随着代码量和依赖的增加而不断提升。Maven作为一个强大的构建工具，简化了这一过程，并通过其插件机制提供了丰富的功能。其中，maven-clean-plugin 是Maven的核心插件之一，它在项目的清理阶段发挥着重要作用。无论是删除旧的编译文件、清理生成的临时文件，还是确保构建环境的整洁，maven-clean-plugin 都是不可或缺的工具。

本文将详细介绍 maven-clean-plugin 的功能、配置方法以及常见的使用场景，帮助开发者更好地理解和利用这一插件，提高项目的构建效率和质量。无论你是Maven的新手还是经验丰富的开发者，希望通过这篇文章，你能够深入掌握 maven-clean-plugin 的使用，并在实际项目中得心应手地应用它。

---

---

1、maven-clean-plugin 插件介绍

该插件只有一个插件目标：

• clean:clean，用于尝试清除项目工作目录中因构建而生成的文件。

默认情况下，它会发现并删除在 project.build.directory、project.build.outputDirectory、project.build.testOutputDirectory 和 project.reporting.outputDirectory 所配置的目录。

通过配置 <filesets/> 元素也可以删除默认目录以外的文件。

---

2、Maven 配置项解释

2.1、project.build.directory

• 默认值：target
• 说明：这是 Maven 项目构建的输出目录，所有构建的输出文件（如编译的类文件、JAR 包等）都会放在这个目录中。

2.2、project.build.outputDirectory

• 默认值：target/classes
• 说明：这是编译主源码的输出目录，所有编译后的主类文件都会放在这个目录中。

2.3、project.build.testOutputDirectory

• 默认值：target/test-classes
• 说明：这是编译测试源码的输出目录，所有编译后的测试类文件都会放在这个目录中。

2.4、project.reporting.outputDirectory

• 默认值：target/site
• 说明：这是生成报告（如站点文档）的输出目录，所有生成的报告文件都会放在这个目录中。

2.5、在 pom.xml 中的配置示例

虽然这些配置项有默认值，但你可以在 pom.xml 文件中自定义这些目录的位置。下面是一个示例，展示了如何在 pom.xml 文件中配置这些项：

<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>my-app</artifactId><version>1.0-SNAPSHOT</version><build><directory>custom-target</directory><outputDirectory>custom-target/classes</outputDirectory><testOutputDirectory>custom-target/test-classes</testOutputDirectory></build><reporting><outputDirectory>custom-target/site</outputDirectory></reporting></project>

---

3、配置 <filesets/> 元素

通过在 pom.xml 文件中配置 <filesets> 元素，你可以指定需要删除的额外文件和目录。每个 <fileset> 元素允许你定义一个文件集，包括目录、包含的文件模式和排除的文件模式。

下面是一个示例，展示了如何在 pom.xml 中配置 maven-clean-plugin 插件以删除默认目录之外的文件和目录：

<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>my-app</artifactId><version>1.0-SNAPSHOT</version><build><plugins><plugin><!-- 指定 maven-clean-plugin 插件 --><groupId>org.apache.maven.plugins</groupId><artifactId>maven-clean-plugin</artifactId><version>3.1.0</version><configuration><!-- 配置 excludeDefaultDirectories 元素以删除时排除项目的默认输出目录, 默认 false--><excludeDefaultDirectories>false</excludeDefaultDirectories><!-- 配置 failOnError 元素以在删除时出现错误，仍继续进行构建, 默认 false--><failOnError>true</failOnError><!-- 配置 followSymLinks 元素以在删除时遵循符号链接, 默认 false--><followSymLinks>false</followSymLinks><!-- 配置 retryOnError 元素以在第一次尝试删除失败时进行再次尝试删除文件, 默认 false--><retryOnError>true</retryOnError><!-- 配置 skip 元素以禁用插件的执行, 默认 false--><skip>false</skip><!-- 配置 verbose 元素以设置插件用详细模式运行, 默认 false--><verbose>false</verbose><!-- 配置 filesets 元素以删除默认目录之外的文件和目录 --><filesets><fileset><!-- 要删除的额外目录 --><directory>extra-directory</directory><!-- 包含 extra-directory 目录中的所有文件和子目录 --><includes><include>**/*</include></includes><!-- 排除 extra-directory 目录中的所有 .txt 文件 --><excludes><exclude>**/*.txt</exclude></excludes></fileset><fileset><!-- 要删除的另一个额外目录 --><directory>another-directory</directory><!-- 仅包含 another-directory 目录中的所有 .log 文件 --><includes><include>**/*.log</include></includes></fileset></filesets></configuration></plugin></plugins></build>
</project>

其中文件集中的目录是项目中的相对路径，换句话说，

<directory>some/relative/path</directory>

相当于：

<directory>${basedir}/some/relative/path</directory>

---

4、其他可选插件元素

4.1、配置 <excludeDefaultDirectories/> 元素

删除时排除项目的默认输出目录。如果设置为 true（默认为 false），则仅删除通过 <filesets> 元素选择的文件和目录。

Ps：从 3.0.0 版本开始，对应的 property 名称已从 clean.excludeDefaultDirectories 变为 maven.clean.excludeDefaultDirectories。

4.2、配置 <failOnError/> 元素

如果在删除时出现错误，是否仍继续进行构建。

使用场景：

• 设置为 false：适用于你希望在清理过程中即使出现错误也不影响整个构建流程的场景。例如，你知道某些文件可能会被其他进程锁定而无法删除，但这并不影响后续的构建步骤；
• 设置为 true：适用于你希望严格控制构建过程，确保所有步骤都无错误完成的场景。例如，清理步骤对于构建的准确性至关重要，任何错误都可能导致后续步骤失败。

4.3、配置 <followSymLinks/> 元素

从项目默认输出目录中删除文件时是否应遵循符号链接。默认为 false。不遵循符号链接需要更多 IO 操作和堆内存，而不管符号链接是否实际存在。因此，如果项目的输出目录很大，并且故意不包含符号链接，则可以通过将此参数设置为 true 来提高性能。从 3.0.0 版本开始，该属性已从clean.followSymLinks 重命名为 maven.clean.followSymLinks。

符号链接（Symbolic Link），也称为软链接（Soft Link），是一种特殊的文件类型，它包含指向另一个文件或目录的路径。符号链接本身并不包含数据，而是一个指针，指向目标文件或目录的位置（类似于 Windows 中的快捷方式）。

Ps：从 3.0.0 版本开始，该属性已从clean.followSymLinks 重命名为 maven.clean.followSymLinks。

4.4、配置 <retryOnError/> 元素

指示如果第一次尝试删除失败，则是否应进行再次尝试（在短暂延迟后）删除文件。这是为了帮助删除由第三方工具（如病毒扫描程序或搜索索引）临时锁定的文件。

4.5、配置 <skip/> 元素

禁用插件的执行。

Ps：从 3.0.0 版本开始，对应的 property 已从 clean.skip 重命名为 maven.clean.skip。

4.6、配置 <verbose/> 元素

设置插件是否以详细模式运行。从 2.3 版本开始，默认值来自 Maven 的全局 debug 标志（命令行开关 mvn clean -X）。

详细模式是一种调试模式，它使插件在执行过程中输出更多的详细信息。这些信息可以帮助开发人员了解构建过程中的每一步，特别是在排查问题时非常有用。详细模式通常包括以下内容：

• 详细的操作步骤：包括每个文件的处理、删除等操作；
• 详细的插件配置：展示插件的配置参数及其值；
• 详细的日志信息：记录插件执行过程中生成的所有日志。

Ps：从 3.0.0 版本开始，该 property 已从 clean.verbose 重命名为 maven.clean.verbose。