Maven install后依赖乱码？排查编译到运行全链路编码问题

“mvn install 框架后引入依赖输出乱码”这句话我帮同事排查过不下十次。现象几乎一模一样你自己维护了一个公共模块或者公司内部的 starter本地跑测试全绿执行mvn install装进本地仓库然后新开一个项目在pom.xml里加上依赖坐标一启动就看见控制台冒出一堆“鎴愬姛”“锟斤拷”。最让人崩溃的是同一个 jar 在 Windows 上乱码到 Linux 上可能又好了甚至在 IDEA 里点运行没事换命令行java -jar就乱。今天不打算只给一个“把编码改成 UTF-8”的结论而是把这条依赖链路上每个会出乱码的位置都拆开讲清楚它为什么会乱、怎么判断是哪一环、以及每类场景的配置怎么改。1. 先看链路mvn install、依赖引入、乱码出现在哪个环节1.1 三个环节三种乱码先别急着改配置依赖引入这个动作本身不会导致乱码。“输出乱码”的本质是字节序列被某个组件按错误的字符集解码。在一个完整的 Maven 项目链路里可能出乱码的位置其实只有三个编译期源码被 javac 用什么编码读取决定 class 文件常量池里的字符串是否已经错掉。资源处理期src/main/resources下的 properties、xml、txt 等文件在 maven-resources-plugin 复制或过滤时按什么编码读写。运行输出期JVM 内部字符串是正常的但日志框架或者System.out输出字节流后终端用了另一种编码显示。很多人的误区是把这三个位置混在一起。改终端编码之前必须先确认字符串在源头是否已经损坏。我把这个过程类比成“装箱和卸货”编译是装箱运行是卸货。装箱的人用 GBK 写说明书卸货的人用 UTF-8 读说明书货再好也白搭。乱码不是某一环单独造成的而是装货人和卸货人用的规则不一致。1.2 最容易踩中的最小复现场景我用一个最简单的场景把这个链路固定下来。框架模块 Acommon-demo里面有一个类public class CommonMsg { public static final String SUCCESS 处理成功; }业务模块 B在pom.xml里引入 A 的坐标主类打印CommonMsg.SUCCESS。A 在中文版 Windows 命令行执行mvn install且 pom 里没有显式声明任何编码。此时 maven-compiler-plugin 会使用平台默认字符集读取源码——在中文版 Windows 上大概率是 GBK。而你的源码文件如果是 IDEA 默认创建的 UTF-8javac 用 GBK 去解码class 内部的“处理成功”就已经是乱码。后面无论你在 B 项目里怎么设置控制台、怎么加启动参数都救不回来因为字节流在编译期就已经错了。这里还有一个很多人不知道的细节class 文件内部的字符串常量统一按 Modified UTF-8 存储所以“class 文件是 GBK 的”这种说法不准确。准确的描述是javac 在解析源码时把字符解错了再编码成 class 规范要求的 UTF-8里面的字符串语义已经坏了。这一点在定位时会很有用。2. 编译期编码为什么同一个框架换个机器 install 出来就乱码2.1 Maven 不声明 sourceEncoding 时的真实行为maven-compiler-plugin 在未显式配置encoding或project.build.sourceEncoding时会依赖 JVM 的默认字符集。也就是说中文版 Windows默认 file.encoding 接近 GBKwindows-936Linux / macOS默认是 UTF-8同一份 UTF-8 源码在 Windows 上执行mvn install和在 macOS 上执行mvn install打出来的 jar 内部字符串可能是完全不同的。这就是“框架在我电脑上好好的到别的环境就乱码”的最常见原因。JDK 18 之后 javac 默认改用 UTF-8JEP 400但这个默认只在直接敲javac命令时稳定成立Maven 插件在不同 JDK 版本上的行为并不完全一致。所以别依赖默认值必须在 pom 里显式声明编码。另外还有一个隐藏影响maven.compiler.encoding属性、project.build.sourceEncoding属性和 compiler 插件encoding配置项三者作用范围略有差别但最终都会影响 javac 读取源码时用的字符集。建议在 properties 里统一声明避免只设置了其中一个换一台机器又失效。2.2 javac 把 UTF-8 当 GBK 读的惨案以及“鎴愬姛”是怎么来的先看编码过程。源码文件本质上是一个字节序列javac 必须知道“用什么字符集去解码这些字节”。解码之后形成字符序列再编码进 class 常量池。举一个具体的例子。“成功”二字的 UTF-8 字节是E6 88 90 E5 8A 9F如果用 GBK 双字节解码E6 88→ 鎴90 E5→ 愬8A 9F→ 姛于是“成功”就变成了“鎴愬姛”。所以当你看到控制台出现一堆“鎴愬姛”这种既像繁体又不像繁体的字可以立刻判断这是 UTF-8 字节被 GBK 解读了。反过来也有另一类常见火星文“涓撳”“寮€濮? 这种是 GBK 字节被当成 UTF-8 解读的结果。两者的根源不同修复方向也不同。网上很多“万能设置”之所以对一部分人无效就是因为没判断到底是哪边解码错了。字符串如果只有 ASCII不受影响中文字符才会触发这种问题。所以经常能看到一个诡异现象程序英文日志全部正常只有中文日志变成火星文。这也侧面说明问题出在编码环节而不是网络问题或依赖包丢失。2.3 资源文件复制过滤另一道容易被忽略的编码门除了编译阶段mvn install打包资源文件时也有一道编码门。如果你只是把src/main/resources下的文件原样复制进 jar且没有启用 filtering多数情况下插件是直接拷贝字节不涉及字符集转换。但一旦 pom 里对资源配置了resources resource directorysrc/main/resources/directory filteringtrue/filtering /resource /resourcesmaven-resources-plugin 就会对文件做变量替换这时候它必须按某种编码读取源文件再按某种编码写出。如果project.build.sourceEncoding没设在 Windows 上就可能把 UTF-8 的 properties 文件读进来按 GBK 写出去运行方再按 UTF-8 读取就又乱码了。properties 文件还有它自己的特例java.util.Properties.load()默认按 ISO-8859-1 解析中文必须写\uXXXX转义否则即使文件本身是 UTF-8读取时也会变成乱码。Spring Boot 的application.properties是一个例外因为它内部做了 UTF-8 处理。但如果你是自定义 starter自己写工具类读取配置文件就很容易踩中这个坑。框架类项目经常同时踩中编译和资源两条线排查时需要一并考虑。3. 一次完整的排查过程从 jar 内检查到终端显示逐层拆3.1 第一件事打开 jar看 class 里的字符串是否已经乱掉遇到“mvn install 框架后引入依赖输出乱码”我建议先看安装到本地仓库的 jar 内部字节码这是定性的关键一步。假设本地仓库路径是默认的~/.m2/repositoryjar 坐标是com.example:common-demo:1.0.0cd ~/.m2/repository/com/example/common-demo/1.0.0 jar tf common-demo-1.0.0.jar javap -c -p -classpath common-demo-1.0.0.jar com.example.CommonMsgjavap会把 class 里的字符串常量直接打印出来。如果“处理成功”已经显示成“鎴愬姛”那就是编译期已经坏了后面所有修复都在白费力气。如果 javap 输出正常说明字节码没有损坏问题大概率在运行端编码不对称。这一步最值钱的地方在于它能把问题的责任方一刀切开。字节码坏了找 Maven 编译配置字节码好着就找终端、JVM 参数和日志框架。3.2 检查 jar 内资源文件的实际编码如果框架里带的是 properties、xml、yml 等配置文件还需要把 jar 里的资源文件解压出来看编码。unzip -p common-demo-1.0.0.jar conf/app.properties app.properties然后看文件内容。在 Windows 上可以快速用 PowerShell 验证$bytes [System.IO.File]::ReadAllBytes(app.properties) # 先按 UTF-8 解一次 [System.Text.Encoding]::UTF8.GetString($bytes) # 再按 GBK 解一次 [System.Text.Encoding]::GetEncoding(936).GetString($bytes)哪一次能正确显示中文说明文件实际就是哪种编码。这样就能判断是“打包时资源文件被转换错了”还是“读取代码用的字符集不对”。3.3 区分“程序内部乱码”和“终端显示乱码”排查到这一步剩下的问题集中在运行输出端。常见的情况是字节码和资源文件都正常但程序启动后中文乱码。这时需要区分到底是字符串在 JVM 内部就错了还是终端显示错了。区分方法很简单把标准输出重定向到文件再打开文件看内容。java -jar your-app.jar out.log 21然后用文本编辑器看out.log。如果文件里是正常可读的中文但终端显示乱码那纯粹是终端字符集问题。如果文件里已经是“锟斤拷”之类的乱码说明 JVM 内部字符串已经出问题通常是启动参数里的file.encoding不对或者输入给程序的资源本身有误。从乱码的形态也可以快速判断方向乱码现象大概率原因形如“鎴愬姛”UTF-8 字节被 GBK 解读形如“涓撳”“寮€濮?GBK 字节被 UTF-8 解读出现“锟斤拷”编码转换过程中发生过字符丢失替换字符 UFFFD再编码出现大量问号?转换时信息已经丢失通常不可逆需要回到源头这个判断表能省很多时间尤其当你面对“同一个 jar 在不同终端一个乱一个不乱”的时候。3.4 打印运行期的实际编码别靠猜Java 程序运行时的默认编码可以通过一个简单代码打印System.out.println(System.getProperty(file.encoding)); System.out.println(Charset.defaultCharset());也可以用 JDK 自带的命令java -XshowSettings:properties -version它会打印出一堆系统属性重点看file.encoding和sun.jnu.encoding。很多 Windows 场景下一个是 GBK另一个也是 GBKIDEA 里配置了-Dfile.encodingUTF-8后才会变成 UTF-8。所以“在 IDEA 运行正常命令行运行乱码”往往就是这个参数差异造成的。注意一个细节System.out在 JVM 启动早期就会读取file.encoding并设置输出流编码如果你在程序运行时才用System.setProperty去改大概率不会生效。真正要改的是启动命令或容器环境变量。4. 高频场景的直接修复方案直接抄作业4.1 场景一Windows 命令行 mvn install 后引入依赖乱码这是最典型的场景。根因是编译期源码编码与平台默认编码不一致。修复方式是在父 pom 或当前模块里固定编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding maven.compiler.encodingUTF-8/maven.compiler.encoding /properties更稳的做法是同时配置 maven-compiler-plugin 和 maven-resources-pluginbuild plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.13.0/version configuration source1.8/source target1.8/target encodingUTF-8/encoding /configuration /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId version3.3.1/version configuration encodingUTF-8/encoding /configuration /plugin /plugins /build改完之后重点是一定要重新mvn clean install。如果只执行mvn install旧 class 可能没被清理jar 里混着旧字节码你会觉得“改了根本没效果”。4.2 场景二日志输出中文乱码很多自定义框架或 starter 会自带 logback / log4j2 配置。如果默认没指定 Console 输出编码在 Windows 上就可能乱。logback 的写法appender nameSTDOUT classch.qos.logback.core.ConsoleAppender encoder pattern%d{HH:mm:ss.SSS} %-5level %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appenderlog4j2 的写法Console nameConsole targetSYSTEM_OUT PatternLayout pattern%d{HH:mm:ss.SSS} %-5level %logger{36} - %msg%n charsetUTF-8/ /Console如果你接手一个已经乱码的框架日志先看它的 starter 里有没有 logback-spring.xml 或 log4j2.xml没有charset就补上。别小看这一项很多“框架引入后日志乱码”的问题既不是编译问题也不是终端问题纯粹是日志框架默认用了平台编码。4.3 场景三properties 配置文件读取乱码如果你在框架里用Properties.load()读取配置文件而配置文件是 UTF-8那一定会乱因为Properties.load()默认按 ISO-8859-1 解析。两种修法读取时明确指定字符集例如用InputStreamReader包一层再交给 Properties。在编辑工具里把中文写成\uXXXX转义例如 IDEA 的 File Encodings 中勾选 “Transparent native-to-ascii conversion”保存时 IDE 会自动把中文转成转义形式。如果框架是 Spring Boot starter那好消息是 Spring Boot 对 application.properties 默认按 UTF-8 处理重点反而是确保打包资源时不要被 maven-resources-plugin 搞坏编码。4.4 场景四IDEA / VSCode / cmd 终端显示乱码字节码和资源都没问题终端还是乱码这是纯输出解码不对称。几个终端常用的修复Windows cmd执行chcp 65001把代码页切到 UTF-8。PowerShell 里可以设置[Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8IDEASettings - Editor - File Encodings把 Global Encoding、Project Encoding、Properties Files 全部选 UTF-8Terminal 设置里的默认编码也改成 UTF-8。VSCode可以直接在终端设置里给 Windows 的默认 profile 增加参数/K chcp 65001 nul让每次打开终端自动切到 UTF-8 代码页。这里提醒一句chcp 65001在旧版 Windows Console 上可能引发光标错位、字体渲染异常等问题。优先使用 Windows Terminal 或 IDE 内置终端体验会好得多。4.5 场景五Tomcat 或 Web 容器启动输出乱码框架如果是一个 Web 应用或 starterTomcat 启动日志乱码也是重灾区。原因不复杂Tomcat 的catalina.bat启动脚本没有指定 JVM 编码而java.util.logging控制台 Handler 默认按平台编码输出。修复方式在catalina.bat或 JVM 参数里加-Dfile.encodingUTF-8修改conf/logging.propertiesjava.util.logging.ConsoleHandler.encoding UTF-8如果运行在 Docker 容器里还需要注意基础镜像的 locale。很多精简镜像的LANG是 CJVM 默认字符集可能变成 ANSI_X3.4-1968中文直接变问号。建议在 Dockerfile 里显式设置ENV LANGC.UTF-8 ENV JAVA_TOOL_OPTIONS-Dfile.encodingUTF-85. 把编码约定固化到工程从 parent pom 到运行脚本一次弄完5.1 统一 parent pom 是最值钱的投资如果你所在项目组有公共 parent pom强烈建议把编码配置全部放进去让每个子模块自动继承。否则每次新项目都要重新配一遍总会有漏网之鱼。上面的 compiler 和 resources 插件配置足够覆盖大多数 Maven 工程。关键点是project.build.sourceEncoding一定要在properties里声明因为很多插件包括 maven-surefire-plugin、maven-javadoc-plugin也都会读取这个属性。5.2 构建环境、CI 和运行脚本一起统一代码层面配好之后构建环境也要同步。建议在 CI 或 Dockerfile 里设置export MAVEN_OPTS-Dfile.encodingUTF-8 export LANGC.UTF-8 export LC_ALLC.UTF-8运行 jar 时也尽量显式指定编码java -Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8 -jar app.jarsun.jnu.encoding影响文件名的编码处理处理中文文件名时也很关键。两个参数一起设置比只设file.encoding更稳。5.3 IDE 与 EditorConfig 收尾源码从一开始就应该是 UTF-8而不是靠编译时“纠正”。建议在项目根目录放一份.editorconfigroot true [*] charset utf-8 end_of_line lf insert_final_newline trueIDEA 里手动确认 Settings - Editor - File Encodings 的三处都是 UTF-8。这样新加入的 Java 文件、配置文件默认就是 UTF-8从源头上减少后续的编码纠纷。6. 实战中那些“改了半天没效果”的隐藏原因6.1 没有 clean install旧 class 残留这是最隐蔽的坑。mvn install在不 clean 的情况下编译器只编译发生变化的文件。如果你只改了 pom 编码配置没改 Java 文件那个已经用 GBK 编译过的 class 不会重新编译jar 里仍然是旧字节码。只有在 pom 配置改动较大或者你主动mvn clean install时所有 class 才会重新生成。我见过太多人改完配置后看到“没效果”最后发现是旧 class 在作怪。6.2 本地仓库缓存和 SNAPSHOT 版本机制依赖方在pom.xml里引入框架坐标后Maven 不是每次都去本地仓库重新扫描的。Release 版本会被缓存SNAPSHOT 版本虽然有远程检查机制但远程仓库与本地仓库的时间同步也可能造成“明明 install 了依赖却还是老版本”的错觉。排查时可以强制更新mvn clean install -U或者直接看本地仓库对应 jar 的时间戳ls -l ~/.m2/repository/com/example/common-demo/1.0.0/6.3 IDEA 编译输出和命令行 Maven 产物不一致这是最容易让人误判的地方。IDEA 里直接运行项目依赖的 A 模块可能是 IDEA 自身的编译输出而不是本地仓库那个由mvn install打出来的 jar。IDEA 的编译器使用的是 IDE 的编码设置命令行 Maven 使用的是 platform 或 pom 编码两者产物可能完全不同。所以经常出现IDEA 里跑得好好的同事在命令行启动 B 项目引入 A 的依赖后乱码。这不是依赖坐标配错了而是你真正跑起来用的字节码根本不是同一个来源。遇到这种问题最好先统一所有入口的构建方式或者在测试环境只用命令行 Maven 构建。6.4 依赖树里悄悄引入了旧版本当 B 项目出现莫名其妙的乱码时先查依赖树确认它确实引用了你刚 install 的坐标版本mvn dependency:tree -Dincludescom.example:common-demo有时候是父 pom 统一管理了依赖版本子项目里声明的坐标被覆盖成了另一个旧版而旧版恰好在别的时候被打包成乱码。这种情况和你最近改的编码配置完全不冲突但表现却一样都是乱码很容易让人方向跑偏。6.5 shade / assembly 插件在打 fat jar 时二次处理资源如果框架或主应用用了 maven-shade-plugin、maven-assembly-plugin 来打 fat jar它们的资源合并逻辑可能再次改变文件编码或覆盖同名文件。建议在合并之前先确认单个 jar 是否正常。如果单个 jar 正常合并之后才乱码那问题就在 shade 或 assembly 的编码配置或资源过滤器上而不是最初的 Maven 编译配置。我个人现在排查这类报错的第一反应永远是一句话先别碰运行配置去解压 jar 看 class 里的字符串正常不正常。如果 class 正常问题在终端和运行时字符集如果 class 已经乱mvn install那台机器上的编译编码背锅。只要顺着字节流走一遍乱码一定会在某一环现出原形。这个问题看起来小但它坑过很多人希望这篇把链路说透之后你下次能五分钟定位而不是折腾一晚上。