当前位置：首页 > news >正文

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

news 2025/10/13 8:06:31

✅ 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 {@Testpublic 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 源与目标版本	✅ 必须设置