Maven 设置项目编码，防止编译打包出现编码错误

✅ Maven 设置项目编码，防止编译打包出现编码错误

作者说明： 本文通过实际示例演示如何在 Maven 项目中正确设置编码，

避免中文源码或注释在编译、打包、测试时出现乱码或"不可映射字符"错误。
说明： 以下内容仅用于技术分享，如有侵权请联系删除。

---

🧩 一、为什么要设置编码

Java 源文件本身是文本文件，字符编码（如 UTF-8、GBK）决定了其中字符的存储方式。

如果源文件的实际编码与编译器使用的编码不一致，就会在编译时出现错误或乱码。

最常见的错误信息是：

编码GBK的不可映射字符

这通常意味着：源码是 UTF-8 保存的，而 Maven 编译器却用 GBK 去解码。

---

⚙️ 二、正确的编码配置（推荐 UTF-8）

在 pom.xml 中，通过 <properties> 和 <build> 标签指定项目的统一编码：

<properties>
    <!-- 指定源代码使用的 Java 版本 -->
    <maven.compiler.source>8</maven.compiler.source>
    <!-- 指定生成的字节码目标版本 -->
    <maven.compiler.target>8</maven.compiler.target>
    <!--设置项目编译的字符编码为UTF-8--> 
    <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
    <!-- 设置项目源码的字符编码为 UTF-8 -->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- 报告输出文件使用的编码（Maven 生成的站点、报告） -->
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

💡 说明：

• <project.build.sourceEncoding>：控制编译时源码读取的编码。
• <project.reporting.outputEncoding>：控制 Maven 生成报告文件的编码。
• <encoding>：maven-compiler-plugin 插件自身的编码设置。

---

🧠 三、验证 UTF-8 配置是否生效

1️⃣ 示例源码（UTF-8 编码）

文件：src/test/java/CodeTest.java

import org.junit.Test;

public class CodeTest {
    @Test
    public void test() {
        System.out.println("你好");
    }
}

2️⃣ 编译与运行

PS D:\live\projects\IDEA\JDBC> mvn compile
PS D:\live\projects\IDEA\JDBC> mvn test -Dtest=CodeTest#test
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running CodeTest
你好
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.032 sec

✅ 可以看到测试输出正常显示中文"你好"，说明编码配置正确。

---

🚫 四、错误示例（编码不一致：GBK）

如果我们错误地将项目的编码改为 GBK：

<properties>
    <!-- 指定源代码使用的 Java 版本 -->
    <maven.compiler.source>8</maven.compiler.source>
    <!-- 指定生成的字节码目标版本 -->
    <maven.compiler.target>8</maven.compiler.target>
    <!--设置项目编译的字符编码为UTF-8--> 
    <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
    <!-- 设置项目源码的字符编码为 UTF-8 -->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- 报告输出文件使用的编码（Maven 生成的站点、报告） -->
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

然后重新编译：

PS D:\live\projects\IDEA\JDBC> mvn clean
PS D:\live\projects\IDEA\JDBC> mvn compile

输出：

[WARNING] 编码GBK的不可映射字符

继续运行测试：

PS D:\live\projects\IDEA\JDBC> mvn test -Dtest=CodeTest#test

报错如下：

[ERROR] /src/test/java/MybatisDemoTest.java:[17,17] 编码GBK的不可映射字符
[ERROR] /src/test/java/MybatisDemoTest.java:[43,56] 对于User(...), 找不到合适的构造器

📘 原因分析：

当源码实际是 UTF-8 编码，而 Maven 编译器认为是 GBK 时，

在编译阶段解码失败，部分字符损坏，

导致中文注释、变量名或字符串常量被错误解析，最终引发"不可映射字符"甚至"构造器签名不匹配"的编译错误。

---

🧩 五、关于 <project.reporting.outputEncoding>

该属性只影响 Maven 生成报告文件（如 site、plugin 报告） 的编码。

不会影响源码编译或程序运行。

建议统一设置为 UTF-8，保持整个项目的字符集一致性。

---

🧭 六、总结

场景	推荐设置
源码文件编码	UTF-8
Maven 编译器编码	<encoding>UTF-8</encoding>
报告输出编码	<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
操作系统或 IDE 字符集	保持一致（UTF-8）

✅ 总结一句话：

Maven 编译时的字符编码必须与源码文件的实际编码一致。

推荐在 pom.xml 中统一使用 UTF-8，以确保跨平台构建和测试过程无乱码问题。

---

📚 附：常见 Maven 编码相关属性

属性名	作用	是否必须
project.build.sourceEncoding	编译源码时使用的编码	✅ 推荐设置
maven.compiler.encoding	编译插件使用的编码参数	✅ 可选
project.reporting.outputEncoding	Maven 报告输出文件编码	✅ 推荐设置
maven.compiler.source / target	Java 源与目标版本	✅ 必须设置