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

Maven 核心插件 maven-resources-plugin 负责处理项目中的资源文件。它的主要功能是将资源从源目录（如 src/main/resources）复制到目标目录（如 target/classes），并在此过程中进行必要的过滤和替换操作，如替换占位符变量。这个插件通常在 Maven 构建生命周期的 process-resources 和 process-test-resources 阶段被执行，用于处理主资源和测试资源。

文章目录

- - [1、maven-resources-plugin 插件介绍](#1、maven-resources-plugin 插件介绍)
  - [2、`resources:resources` 插件目标](#2、resources:resources 插件目标)
  - - [2.1、必选参数 `` 元素](#2.1、必选参数 `` 元素)
    - [2.2、可选参数`` 元素](#2.2、可选参数`` 元素)
    - [2.3、可选参数`` 元素](#2.3、可选参数`` 元素)
    - [2.4、可选参数`` 元素](#2.4、可选参数`` 元素)
    - [2.4、可选参数`` 元素](#2.4、可选参数`` 元素)
    - [2.5、可选参数`` 元素](#2.5、可选参数`` 元素)
    - [2.6、可选参数`` 元素](#2.6、可选参数`` 元素)
    - [2.7、可选参数`` 元素](#2.7、可选参数`` 元素)
    - [2.8、可选参数 `` 元素](#2.8、可选参数 `` 元素)
    - [2.9、可选参数 `` 元素](#2.9、可选参数 `` 元素)
    - [2.10、可选参数 `` 元素](#2.10、可选参数 `` 元素)
    - [2.11、可选参数 `` 元素](#2.11、可选参数 `` 元素)
    - [2.12、可选参数 `` 元素](#2.12、可选参数 `` 元素)
    - [2.13、可选参数 `` 元素](#2.13、可选参数 `` 元素)
    - [2.14、可选参数 `` 元素](#2.14、可选参数 `` 元素)
    - [2.15、可选参数 `` 元素](#2.15、可选参数 `` 元素)
    - [2.16、可选参数 `` 元素](#2.16、可选参数 `` 元素)
  - [3、`resources:testResources ` 插件目标](#3、resources:testResources 插件目标)
  - [4、`resources:copy-resources` 插件目标](#4、resources:copy-resources 插件目标)

1、maven-resources-plugin 插件介绍

资源插件负责将项目资源到输出目录。Maven 项目有两种不同的资源：主资源和测试资源。区别在于，主资源（默认在 src/main/resources 目录）是与主源代码（位于 src/main/java 目录下）关联的资源，而测试资源（默认在 src/test/resources 目录）与测试源代码（位于 src/main/test 目录下）关联。从 2.3 版本开始，该插件可以使用 Maven 过滤组件来过滤资源。

资源插件将 resource 元素所指定的文件复制到输出目录。

以下三个插件目标仅在指定资源和输出目录的 XML 元素的方式上有所不同。

resources:resources ：将主资源目录 src/main/resources 中的资源复制到构建输出目录 target/classes，并支持过滤；
resources:testResources ：将测试资源目录 src/test/resources 中的资源复制到构建输出目录 target/test-classes，并支持过滤；
resources:copy-resources：允许从任意指定的源目录复制资源到任意指定的目标目录，提供更大的灵活性并支持过滤。

2、`resources:resources` 插件目标

该插件目标的全称为 org.apache.maven.plugins:maven-resources-plugin:3.2.0:resources，主要负责将主源代码的资源复制到主输出目录。该目标通常自动执行，因为它默认绑定到 process-resources 生命周期阶段。它始终使用project.build.resources 元素来指定资源，默认情况下使用 project.build.outputDirectory property 来指定输出目录。

2.1、必选参数 `<outputDirectory/>` 元素

将资源复制到其中的输出目录。默认的值为 ${project.build.outputDirectory} 即 target/classes （Maven 项目的默认输出目录路径，用于存放编译后的类文件和主资源文件）

2.2、可选参数`<delimiters/>` 元素

指定在资源中进行筛选的表达式的分隔符。这些分隔符以 beginToken*endToken 的形式指定。如果未给出 *，则假定起始和结束的分隔符相同。因此，可以将默认筛选分隔符指定为：

xml 复制代码

<delimiters>
  <delimiter>${*}</delimiter>
  <delimiter>@</delimiter>
</delimiters>

当分隔符两端相同（如 @），无需指定 @*@。这表示起始和结束标记相同，简化了配置。

PS：筛选机制允许你在资源文件中使用占位符，并在构建过程中用实际的值替换这些占位符。占位符的分隔符决定了哪些文本会被识别为占位符。

另外使用 <delimiters/> 生效需要确保启用了筛选功能：在资源配置中，确保 filtering 属性设置为 true。

xml 复制代码

        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <includes>
                    <include>**/*</include>
                </includes>
              	<!-- 启用筛选功能 -->
                <filtering>true</filtering> 
            </resource>
        </resources>

假设你的资源文件 config.properties 中有以下内容：

properties 复制代码

app.version=${project.version}
app.name=@project.name@

在构建过程中，Maven 会根据分隔符替换这些占位符：

${project.version}：将被替换为 pom.xml 中定义的 ${project.version} 的值；
@project.name@：将被替换为 pom.xml 中定义的 ${project.name} 的值。

2.3、可选参数`<outputDirectory/>` 元素

除了自定义分隔符（如果有）之外，还使用默认分隔符。默认为 true。

2.4、可选参数`<encoding/>` 元素

读取和写入筛选资源时要使用的字符编码。默认的值使用 ${project.build.sourceEncoding} ，通常在 pom.xml 中定义该属性，以确保一致的字符编码。

2.4、可选参数`<escapeString/>` 元素

指定一个转义字符串，以防止某些表达式被替换。带有此转义字符串的表达式在处理资源文件时不会被替换，而是保持原样或进行特定的转义处理。

2.5、可选参数`<escapeWindowsPaths/>` 元素

用于指定是否在 Windows 样式路径中转义反斜杠和冒号。这个设置可以在某些情况下避免路径解析错误，特别是当路径中包含特殊字符时。

默认情况下，<escapeWindowsPaths/> 的值为 true，表示会自动进行转义。例如，路径 C:\Users\Example\ 会被转义为 C:\\Users\\Example\\。

2.6、可选参数`<fileNameFiltering/>` 元素

用于支持过滤特定的文件名、文件夹或路径，这对于精细化控制清理操作非常有用。通过此参数，可以指定需要排除或包含的文件和目录，从而实现更加灵活的清理策略。

2.7、可选参数`<filters/>` 元素

要与 POM build/filters 部分中指定的系统属性、项目属性和过滤器属性一起使用的额外属性文件列表，这些文件应在当前 Mojo 执行期间用于过滤。通常，这些将在插件的 execution 部分进行配置，从而为特定 execution 提供一组不同的过滤器。例如，

从 Maven 2.2.0 开始，您可以选择使用 default-resources 和 default-testResources 来为两种不同类型的资源提供不同的配置。通过提供 extraFilters 配置，您可以区分哪些筛选器用于哪种类型的资源。

2.8、可选参数 `<includeEmptyDirs/>` 元素

复制 resources 元素中包含的任何空目录。默认为 false。

2.9、可选参数 `<mavenFilteringHints/>` 元素

<mavenFilteringHints/> 元素用于配置一组 Plexus 组件，这些组件实现了 MavenResourcesFiltering.filterResources() 方法，并将在资源复制/筛选后执行。该元素的值类型为 java.util.List，允许用户指定多个组件提示。

这些组件提示列表可以用来扩展或自定义资源的过滤和处理过程。通过配置 <mavenFilteringHints/> 元素，可以在资源过滤后执行一系列特定操作，例如日志记录、资源校验、额外的处理逻辑等。

以下是一个示例配置，展示了如何使用 <mavenFilteringHints/> 元素：

xml 复制代码

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <version>3.2.0</version>
            <configuration>
                <mavenFilteringHints>
                    <hint>com.example.maven.filtering.MyCustomFilter1</hint>
                    <hint>com.example.maven.filtering.MyCustomFilter2</hint>
                </mavenFilteringHints>
            </configuration>
        </plugin>
    </plugins>
</build>

在这个示例中，<mavenFilteringHints/> 元素配置了两个自定义的过滤组件 MyCustomFilter1 和 MyCustomFilter2。这些组件将在资源复制和筛选之后执行，执行具体的过滤或处理逻辑。

2.10、可选参数 `<nonFilteredFileExtensions/>` 元素

<nonFilteredFileExtensions/> 元素用于指定在资源过滤过程中不进行过滤的文件扩展名列表。这个列表中的文件扩展名将被排除在过滤操作之外，以确保这些文件在复制过程中保持原样，不受过滤规则的影响。默认情况下，这些扩展名包括：jpg、jpeg、gif、bmp、png。该元素的值类型为 java.util.List。

通过配置 <nonFilteredFileExtensions/>，可以添加或修改不进行过滤的文件扩展名列表，以适应项目的特定需求。

2.11、可选参数 `<overwrite/>` 元素

覆盖现有文件，即使目标文件较新。默认为 false。

2.12、可选参数 `<propertiesEncoding/>` 元素

<propertiesEncoding/> 元素用于指定在读取和写入过滤属性文件时要使用的字符编码。这个参数非常重要，尤其在处理包含特殊字符或多语言内容的属性文件时，可以确保正确的字符编码被使用。如果未指定该参数，它将默认使用 encoding 参数的值。

通过设置 <propertiesEncoding/>，可以明确控制属性文件的编码方式，从而避免因为编码问题导致的文件读取或写入错误

2.13、可选参数 `<skip/>` 元素

如果需要，可以跳过插件的执行。不推荐使用，但有时使用起来相当方便。默认为 false。

2.14、可选参数 `<supportMultiLineFiltering/>` 元素

用于控制在过滤过程中是否支持多行过滤。具体来说，当启用此功能时，Maven 将停止在行末尾搜索 endToken，而是继续跨行搜索，直到找到匹配的 endToken。该参数默认为 false，表示默认情况下不支持多行过滤，即只在当前行内搜索 endToken。

2.15、可选参数 `<useBuildFilters/>` 元素

如果为 false，则在处理此 Mojo 执行中的资源时，不要使用 POM 的 build/filters 部分中指定的过滤器。默认为 true。

2.16、可选参数 `<useDefaultDelimiters/>` 元素

除了自定义分隔符（如果有）之外，还使用默认分隔符。默认为 true。

3、`resources:testResources` 插件目标

该插件目标的全称为 org.apache.maven.plugins:maven-resources-plugin:3.2.0:test-Resources，主要负责将测试源代码的资源复制到测试输出目录。该插件目标通常自动执行，因为默认情况下它与 process-test-resources 生命周期阶段相关联。它总是使用 project.build.testResources 元素指定资源，默认情况下使用 project.build.testOutputDirectory property 指定要输出的目录。

该插件目标支持的可选元素与 resources:resources 插件目标支持的可选元素相同。

4、`resources:copy-resources` 插件目标

该插件目标的全称为 org.apache.maven.plugins:maven-resources-plugin:3.2.0:copy-resources，主要负责将资源复制到输出目录。此目标要求您配置要复制的资源，并指定输出目录。

必选元素：

<outputDirectory>。要将资源复制到其中的输出目录。
<resources>。要转移的资源列表。

可选参数：该插件目标支持的可选元素与 resources:resources 插件目标支持的可选元素相同。

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

文章目录

1、maven-resources-plugin 插件介绍

2、resources:resources 插件目标

2.1、必选参数 <outputDirectory/> 元素

2.2、可选参数<delimiters/> 元素

2.3、可选参数<outputDirectory/> 元素

2.4、可选参数<encoding/> 元素

2.4、可选参数<escapeString/> 元素

2.5、可选参数<escapeWindowsPaths/> 元素

2.6、可选参数<fileNameFiltering/> 元素

2.7、可选参数<filters/> 元素

2.8、可选参数 <includeEmptyDirs/> 元素

2.9、可选参数 <mavenFilteringHints/> 元素

2.10、可选参数 <nonFilteredFileExtensions/> 元素

2.11、可选参数 <overwrite/> 元素

2.12、可选参数 <propertiesEncoding/> 元素

2.13、可选参数 <skip/> 元素

2.14、可选参数 <supportMultiLineFiltering/> 元素

2.15、可选参数 <useBuildFilters/> 元素

2.16、可选参数 <useDefaultDelimiters/> 元素

3、resources:testResources 插件目标

4、resources:copy-resources 插件目标

2、`resources:resources` 插件目标

2.1、必选参数 `<outputDirectory/>` 元素

2.2、可选参数`<delimiters/>` 元素

2.3、可选参数`<outputDirectory/>` 元素

2.4、可选参数`<encoding/>` 元素

2.4、可选参数`<escapeString/>` 元素

2.5、可选参数`<escapeWindowsPaths/>` 元素

2.6、可选参数`<fileNameFiltering/>` 元素

2.7、可选参数`<filters/>` 元素

2.8、可选参数 `<includeEmptyDirs/>` 元素

2.9、可选参数 `<mavenFilteringHints/>` 元素

2.10、可选参数 `<nonFilteredFileExtensions/>` 元素

2.11、可选参数 `<overwrite/>` 元素

2.12、可选参数 `<propertiesEncoding/>` 元素

2.13、可选参数 `<skip/>` 元素

2.14、可选参数 `<supportMultiLineFiltering/>` 元素

2.15、可选参数 `<useBuildFilters/>` 元素

2.16、可选参数 `<useDefaultDelimiters/>` 元素

3、`resources:testResources` 插件目标

4、`resources:copy-resources` 插件目标