maven编码格式

Maven 编码格式配置：统一项目编码避免乱码问题

在 Maven 构建过程中，若出现编码格式不一致（如默认 GBK 与项目 UTF-8 冲突），可能导致资源文件乱码、日志警告或构建失败。本文详细介绍如何统一 Maven 编码格式，确保项目构建的一致性。

编码问题的表现与影响

当 Maven 编码与项目编码不一致时，常见现象包括：

• 构建日志出现警告：[WARNING] Using platform encoding (GBK actually) to copy filtered resources, i.e. build is platform dependent!
• 资源文件（如 *.properties、*.xml）在过滤或复制过程中出现乱码。
• 编译后的 class 文件包含中文乱码，导致运行时异常。

这些问题的核心原因是：Maven 默认使用操作系统的平台编码（如 Windows 通常为 GBK），而项目可能采用 UTF-8 编码。

全局编码配置（推荐）

通过配置环境变量，统一 Maven 所有项目的编码格式，一劳永逸解决问题。

配置 MAVEN_OPTS 环境变量

步骤：

1. 打开系统环境变量配置（Windows 可通过「此电脑→属性→高级系统设置→环境变量」）。

2. 新建系统变量MAVEN_OPTS，值为：

   -Dfile.encoding=UTF-8

3. 重启命令行工具（确保环境变量生效）。

验证：执行 mvn --version，查看输出中 Default locale 对应的编码是否为 UTF-8：

Default locale: zh_CN, platform encoding: UTF-8

原理：-Dfile.encoding=UTF-8 是 Java 虚拟机参数，强制 Maven 及所有子进程使用 UTF-8 编码。

项目级编码配置（细粒度控制）

若需为单个项目指定编码（或覆盖全局配置），可在 pom.xml 中通过属性声明。

配置 project.build.sourceEncoding

在 pom.xml 的 <properties> 中添加：

<project>
  <properties>
    <!-- 统一源码和资源文件的编码 -->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- 可选：指定 Java 编译编码（与 sourceEncoding 通常一致） -->
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <!-- 可选：指定测试源码的编码 -->
    <project.build.testSourceEncoding>UTF-8</project.build.testSourceEncoding>
  </properties>
</project>

作用：

• project.build.sourceEncoding：指定主源码和资源文件的编码，影响 maven-resources-plugin（资源复制）和 maven-compiler-plugin（编译）。
• project.reporting.outputEncoding：指定生成报告（如 Javadoc）的编码。

插件级编码配置（可选）

部分插件（如资源插件、编译插件）可单独配置编码，覆盖全局或项目属性：

<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>

    <!-- 编译插件：控制 Java 源码编译的编码 -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.1</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
        <encoding>UTF-8</encoding> <!-- 源码编译编码 -->
      </configuration>
    </plugin>
  </plugins>
</build>

注意：插件级配置优先级高于项目属性，建议仅在特殊场景下使用（如部分资源需不同编码）。

配置优先级说明

Maven 编码配置的优先级从高到低为：

1. 插件级配置（如 maven-resources-plugin 的 <encoding>）。
2. 项目属性（project.build.sourceEncoding 等）。
3. 全局环境变量（MAVEN_OPTS 中的 -Dfile.encoding）。
4. 操作系统默认编码（最低优先级，不推荐依赖）。

常见问题解决

1. 配置后仍显示 GBK 编码

• 原因：环境变量未生效或被其他配置覆盖。
• 解决：
  • 重启命令行或 IDE，确保 MAVEN_OPTS 生效。
  • 检查 pom.xml 中是否有插件单独指定了非 UTF-8 编码。

2. 资源文件过滤后乱码

• 原因：资源插件使用的编码与文件实际编码不一致。
• 解决：确保 maven-resources-plugin 的 <encoding> 与资源文件编码（如 UTF-8）一致。

3. IDE 中编码正常但命令行构建乱码

• 原因：IDE 可能内置了编码配置，与命令行环境不一致。
• 解决：统一通过 MAVEN_OPTS 配置编码，确保命令行和 IDE 使用相同参数。