那天下午同事把一个从别的机器拷过来的工程丢给我说编译一直报错让我帮忙看两眼。我打开 IDEA按下 BuildBuild Output 面板里滚出来的不是错误行号而是一串像谁闭着眼睛在键盘上乱敲了一通。编译确实是失败的但它死活不肯告诉我为什么失败这才是最让人上火的地方。IDEA 编译乱码、Build Output 提示信息乱码本质上是同一个问题的两种表现——信息在从编译器传到你眼睛的路上被换了三次衣服而链条上任何一环穿错了你看到的就只是问号。这篇文章我想把这件事彻底讲透。我会先从乱码的形态分类讲起因为、锟斤拷、?、□这四种看起来都是乱根因却完全不同很多人第一步就改错了地方。然后我会把编码链路拆成五道关卡逐一分析再给出 IDEA、Maven、Gradle、JDK 四个层面可以直接照抄的配置最后附一份我自己整理的排查清单。无论你是刚装完 IDEA 的新手还是被构建日志折腾过很多次的老手这篇内容应该都能让你下次遇到乱码时少走两小时弯路。1. 先给乱码分个类别一上来就改设置乱码这个词太笼统了笼统到你根本没法据此判断该动哪里。我见过太多人一看到乱码就去 File Encodings 里把三个下拉框全改成 UTF-8然后重启然后发现还乱。不是 UTF-8 不对是他根本没搞清楚眼前这堆符号是怎么被造出来的。1.1 UFFFD 替换字符你那串 的身份证先说你标题里这串。它其实不是六个奇怪的字符而是同一个字符重复了六次——Unicode 里的 UFFFD学名 REPLACEMENT CHARACTER中文一般叫替换字符或你可以自己复制一个到搜索框里对比。它的产生机制特别简单一个解码器拿到了一段字节流按某个字符集规则去解释遇到无法映射到任何合法字符的字节序列它不会报错崩溃而是吐出一个 UFFFD 顶上去。所以的真正含义是我拿到的这段字节用我现在的规则解不出来一共解废了六处。关键推论来了你看到的 的数量和原始字符的数量不是一一对应的。一个中文字在 UTF-8 里占 3 字节如果这 3 字节被按单字节字符集解码可能就变成 3 个 也可能因为解码器做了合并而变成 1 个。所以别去数 的个数猜原文那是在浪费时间直接去看原始字节才是正路。1.2 锟斤拷、问号、豆腐块另外三种乱的来历锟斤拷是中文互联网上最著名的乱码梗很多人当笑话看但它背后是一条非常清晰的错误链条理解了它你对编码的理解会直接上一个台阶。它的成因是两次错误转码的叠加。第一步一段 UTF-8 字节被用错误的方式解码解不出来的部分被替换成 UFFFD。第二步这些 UFFFD 又被按 GBK 编码写出去。UFFFD 在 UTF-8 里是EF BF BD三个字节两个连续的 UFFFD 就是EF BF BD EF BF BD。而在 GBK 里双字节被切成EFBF、BDEF、BFBD三组正好对应三个汉字——就是锟斤拷。所以看到这三个字你可以百分百确定数据在 UTF-8 和 GBK 之间被来回折腾过至少两次问题不在最后一环在前面的某次转换。至于问号?它和 是反过来的。 是解码失败而?通常是编码失败一个字符要写出去但目标字符集里根本没有它编码器就写了个 0x3F 也就是?来占位。这种乱码是不可逆的原始信息在那一刻就丢失了别指望任何工具能还原。最后是空心方块□这压根不是编码问题而是字体缺字——字节流完全正确字符也正确只是你当前的字体里没有这个字的字形渲染器画了个方框。这个区别很重要因为解决它要去改字体设置改编码一点用都没有。1.3 分类不清就会改错地方把上面四种排一排你会发现它们指向完全不同的修复路径要查解码端用的是什么字符集锟斤拷要查中间有没有多余的转码环节?要查编码端的目标字符集是不是太小□要去改字体。而 IDEA 的 Build Output 乱码绝大多数情况是第一种——某个环节用了系统默认的 GBK 去解一段 UTF-8 字节。我给自己定了个规矩动手之前先截个图把乱码形态确认下来。这动作只花十秒钟但能省掉后面反复重启 IDE 的半小时。下面几节我们就把 IDEA 编译这条链路上的每一个环节都摊开看。2. 编码链路一次编译的信息要过五道关卡你可以把编译时看到一行提示信息这件事想象成寄快递源码是包裹javac 是收件员诊断信息是回执IDEA 是快递柜你的显示器是收件人。任何一段路的地址写错了包裹就送不到。2.1 第一关javac 怎么读你的源文件这是链路的起点也是最容易被忽略的一环。javac 读.java文件时需要一个字符集规则把字节流变成字符。如果你没有显式告诉它它就会用平台默认字符集——在中文 Windows 上历史上这个默认值就是 GBK代码页 936。于是矛盾就出现了你的源文件在编辑器里保存成的是 UTF-8因为大家都这么存而 javac 按 GBK 去读。如果文件里全是英文和 ASCII 符号两种规则的结果一模一样你完全察觉不到问题一旦代码里出现中文注释、中文字符串常量javac 读到的就是一堆乱码字符。好消息是编译器对源文件里的乱码通常不会安静地放过——它会报未结束的字符串字面量非法字符之类的错误。坏消息是这条错误信息本身也是中文的它还要再经过后面几道关卡才能到达你眼前所以你可能连这条错误都看不清。这里我给你一个可以直接落地的原则源代码的编码永远显式指定永远不要依赖默认值。不管你在 IDEA 里怎么点命令行里永远带上-encoding UTF-8构建脚本里永远写死编码。2.2 第二关诊断信息是编译器的输出不是源文件的输出这一关是整件事里最反直觉的地方也是大部分人绕不过去的坎。很多人以为我源文件已经是 UTF-8 了那编译输出自然也应该是 UTF-8。不对。诊断信息那些错误提示、警告、行号是 javac 程序自己生成的文本它的字符集取决于 javac 进程运行时的编码环境跟你的源文件编码没有半毛钱关系。具体来说编译器要往外吐一行错误: 找不到符号这行字要先被编码成字节才能通过标准输出流送出去。而它用哪个字符集编码在 JDK 18 之前主要受file.encoding影响在 JDK 18 之后则要看stdout.encoding这个属性。中文版的 JDK 还有一层诊断信息本身是中文的因为user.languagezh这又增加了一次编码的机会。所以当你看到 Build Output 里一堆时正确的怀疑顺序是先怀疑 javac 输出端用的编码和 IDEA 读取端用的编码对不上而不是去怀疑源文件。2.3 第三关子进程到 IDE 的管道javac 在 IDEA 里不是跑在 IDE 进程里的。IDEA 会起一个独立的编译进程或者交给构建工具进程通过标准输出管道把字节流传回来。管道本身是哑的它只搬字节不关心编码也不做任何转换。问题出在两端写的一端按它认为对的字符集把字符变成字节读的一端按它自己认为对的字符集把字节变回字符。只要两端不一致就一定乱码而且这种乱码是完全可以复现、完全可以用工具验证的——你甚至可以在命令行手动跑一遍 javac看它输出到文件里的字节是什么样。我实际排查时最爱用的一招是把构建输出重定向到一个文件然后用十六进制工具看前几个字节。如果中文字符的位置出现的是EF BF BD那就确认了是解码失败产生的 UFFFD往上游找如果看到的是合法的 GBK 双字节但被当成 UTF-8 显示那就是纯粹的字符集错配改编码设置就能好。2.4 第四关IDE 自己的编码与字体渲染字节正确地变成字符之后还有最后一关IDEA 要把这些字符画到屏幕上。这一关有两个可能出问题的地方。第一个是 IDEA 进程自己的默认编码。IDEA 2022.3 之后的版本其内置运行时默认已经按 UTF-8 处理但在老版本或者被自定义 vmoptions 改过的环境里仍然可能出现 IDE 内部编码与子进程不一致。第二个就是字体——你当前编辑器字体如果没有中文字形中文就会被画成方块。这一步和编码无关但症状很容易被误判成编码问题。顺便说一句File Encodings里那个Transparent native-to-ascii conversion勾选框很多人不知道它干什么的。它的作用是让.properties文件在保存时把非 ASCII 字符转成\uXXXX转义形式读取时再转回来。这是 Java Properties 规范的历史遗留Properties 文件规定用 ISO-8859-1跟编译输出乱码没关系别把它当成万能开关。3. 动手改IDEA 侧五个必须过一遍的地方前面讲原理是为了让你改得明白现在进入实操。下面五处是我每次遇到乱码都会按顺序过一遍的绝大多数情况下走完前三步就好了。3.1 File Encodings三个下拉框和一个小勾选框路径是Settings / Preferences → Editor → File Encodings。这里有三个下拉框设置项建议值作用范围Global EncodingUTF-8IDE 全局默认新建项目继承这个Project EncodingUTF-8当前项目覆盖全局Default encoding for properties filesUTF-8properties 文件的读写编码三个都选 UTF-8这是最省心的组合。如果你接手的是一个老工程里面的.properties确实是 GBK 编码的那也不要为了统一去强行改成 UTF-8——那会把文件内容真的改坏。这种情况应该单独给那个目录设置编码在 Project 视图里右键文件 →File Properties → File Encoding只针对这个文件指定。注意修改项目编码后IDEA 可能会问你是否要转换文件内容这里一定要看清再点。选Convert会真的把磁盘上的文件重新编码保存选Reload只是换个方式读。选错会污染整个工程尤其在 Git 里会产生全文件 diff。3.2 Java Compiler 的附加参数路径是Settings → Build, Execution, Deployment → Compiler → Java Compiler。找到Additional command line parameters这一栏填进去-encoding UTF-8这一行的作用就是前面说的第一关——强制 javac 用 UTF-8 读源文件。它不解决输出端的乱码但它是所有后续步骤的前提。如果这一步不做源文件本身就被读错了后面再怎么调输出编码都是在修复一个已经坏掉的东西。同一页面上还有Use compiler选项Javac / Eclipse / Ajc和Build process heap size。如果你用的是 Eclipse 编译器它的编码行为跟 javac 略有差异建议还是切回 Javac社区资料更多行为也更好预测。3.3 自定义 VM Options 该写哪些 -D这是解决输出端乱码的主战场。路径是Help → Edit Custom VM Options会打开idea64.exe.vmoptions文件。我一般会确认里面有这几行-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8 -Dstdout.encodingUTF-8 -Dstderr.encodingUTF-8逐个解释一下。file.encoding是最经典的那个控制 JVM 默认字符集sun.jnu.encoding影响文件名和路径的处理在 Linux/macOS 上尤其重要stdout.encoding和stderr.encoding是 JDK 19 之后引入的、专门控制标准输出和标准错误流的编码这两个才是直接决定你的控制台输出乱不乱的关键参数很多人只写了file.encoding发现没用就是因为漏了它们。提示不要直接改 IDEA 安装目录下的idea64.exe.vmoptions那个文件在 IDE 升级时可能被覆盖。用Edit Custom VM Options生成的用户级副本才是正路。改完必须完全退出 IDEA 再启动只重启项目是不生效的。3.4 Fallback Font 与编辑器字体如果前面三步都做完了Build Output 还是方框那就要考虑字体了。路径是Settings → Editor → Font重点看Fallback font备用字体这一项。它会显示当前字体不支持某些字符的提示。把它设成一个中文字形完整的字体比如Microsoft YaHei、Noto Sans CJK SC或者Sarasa Mono SC。设置完之后编辑器会用主字体渲染 ASCII用备用字体渲染中文两边都不打架。这个设置只影响编辑器和控制台面板的显示不影响文件内容所以可以放心大胆试。顺便说个常识控制台面板的字体其实跟随编辑器字体设置不是单独配的。所以你在 Font 页面改完Build Output 面板会立刻跟着变前提是重新构建一次刷新输出。3.5 清缓存重启的时机和代价File → Invalidate Caches / Restart是个很有效的万能药但它有代价索引需要重建大工程可能要等好几分钟。所以我建议的顺序是先改配置重启一次如果还不行再清缓存。别一上来就清缓存那会掩盖掉真正的原因下次换个项目还会犯。有一个场景确实必须清缓存你改了File Encodings里的项目编码但打开的文件还是用旧编码显示的。这是因为 IDEA 缓存了文件内容清一下缓存能强制重新读取。4. 构建工具层Maven 和 Gradle 各自的开关IDEA 的界面设置管的是 IDE 自己发起的编译。但如果你用的是 Maven 或 Gradle 构建实际的编译是在构建工具进程里完成的编码配置得写到构建脚本里否则命令行构建和 CI 构建照样乱。4.1 Maven三处 encoding 一个都别落下Maven 的编码配置散在三个地方缺一个就可能出问题。第一处是属性区写在pom.xml的properties里properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties第二处是编译器插件的显式配置写在buildplugins里plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.13.0/version configuration encodingUTF-8/encoding source17/source target17/target /configuration /plugin第三处是环境变量MAVEN_OPTS影响 Maven 进程自己的 JVM 编码set MAVEN_OPTS-Dfile.encodingUTF-8为什么三处都要写因为它们的生效范围不同project.build.sourceEncoding是给插件读的默认值maven-compiler-plugin的encoding是最直接的强制项MAVEN_OPTS管的是 Maven 自身进程的输出编码。少了任何一个都可能出现源码读对了但日志乱或者日志正常但源码读错的半吊子状态。4.2 Gradlejvmargs 与 compileJava 双管齐下Gradle 的配置更集中一些。第一处是项目根目录的gradle.propertiesorg.gradle.jvmargs-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8这一行控制的是 Gradle Daemon 进程的编码。这里有个坑Gradle Daemon 是常驻的你改了gradle.properties之后必须让它重启才能生效执行gradle --stop或者在 IDEA 里手动重启 Gradle 同步。第二处是在build.gradle里给所有 JavaCompile 任务统一设置编码tasks.withType(JavaCompile).configureEach { options.encoding UTF-8 }注意我用的是configureEach而不是all。在较新的 Gradle 里all会在配置阶段就实例化所有任务有性能问题configureEach是惰性的更推荐。另外如果你的构建里有Test任务输出中文也要给它们加上编码tasks.withType(Test).configureEach { systemProperty file.encoding, UTF-8 }4.3 多模块工程的编码木桶效应多模块工程有个特别讨厌的现象主模块编译正常某个子模块的日志乱码。原因通常是子模块有自己的pom.xml或者build.gradle没有继承父工程的编码配置。我的做法是在聚合工程的父 POM 里把编码配成pluginManagement的一部分让所有子模块强制继承Gradle 则在根项目的subprojects或者allprojects块里统一配置。判断是否已经统一有个土办法在整个工程目录里搜一遍encoding看看还有哪些文件写了 GBK 或者干脆没写。注意不要为了省事把编码配置写进settings.xml或者全局 Gradle 初始化脚本。那些地方的配置会影响到你所有的项目一旦某个老项目本来就依赖 GBK你会把它一起改坏。项目级的配置就放在项目里这是更稳妥的边界。5. JDK 版本带来的变量有些乱码问题你改了所有设置都没用最后发现是 JDK 版本在作怪。这一节讲两个最容易踩的版本差异。5.1 JDK 18 是个分水岭在 JDK 18 之前JVM 的默认字符集是跟随操作系统的。中文 Windows 的系统默认代码页是 936所以 JVM 的file.encoding默认就是 GBK。你在这种环境下写-Dfile.encodingUTF-8是有实际意义的因为它和白板默认值不一样。JDK 18 通过 JEP 400 把这个默认值改成了 UTF-8不管操作系统是什么。所以从 JDK 18 开始file.encoding的白板值已经是 UTF-8 了你再写一遍不会有害但也不会带来变化。很多人升级 JDK 后觉得我明明配了 UTF-8 怎么还是乱其实问题已经转移到了别的地方。5.2 stdout.encoding 与诊断信息语言JEP 400 改的是file.encoding它没有改标准输出流的编码。JDK 19 之后标准输出流有了独立的编码属性stdout.encoding而它的默认值是跟随系统原生编码的——也就是说在中文 Windows 上它默认还是 GBK。这就造成了一个非常隐蔽的组合状态JVM 内部按 UTF-8 处理字符串往外打印时却按 GBK 编码字节IDEA 那边再按 UTF-8 解码于是每个中文字符都被拆成两个字节各解一次输出一串。这就是为什么我在 3.3 节里强调-Dstdout.encodingUTF-8和-Dstderr.encodingUTF-8这两个参数它们才是真正对齐管道两端的钥匙。再说诊断信息的语言。中文 JDK 会输出中文报错这本身没问题但中文报错要经过更多的编码环节出错概率更高。如果你排查乱码时需要一个干净的环境可以临时加这两个参数把诊断信息强制成英文-Duser.languageen -Duser.countryUS英文报错全是 ASCII任何编码都能正确传输这样你就能把编码问题和代码问题彻底分开。定位完再改回中文就行。6. 控制台之外的同类乱码速查Build Output 乱码只是冰山一角同一套原理在很多地方都会重演。我整理了几个高频场景你把这节的对照表存下来以后遇到能直接对号入座。6.1 构建日志、CI 与远程产物本地正常、CI 上乱码是最典型的环境差异问题。CI 跑在 Linux 容器里容器的 locale 默认往往是POSIX或者C也就是纯 ASCII。这时候任何非 ASCII 字符都会被替换掉。解决办法是在 CI 的构建脚本开头设置环境变量export LANGC.UTF-8 export LC_ALLC.UTF-8C.UTF-8的好处是它不依赖系统里安装了哪套区域数据几乎所有 Linux 发行版都支持比zh_CN.UTF-8更稳。另一种情况是本地 Windows、服务器 Linux日志通过日志采集工具传输。这时候要检查采集工具的读取编码。传输过程中如果经过了错误的转码你在页面上看到的可能就是锟斤拷那就得去找中间环节而不是在 IDEA 里瞎调。6.2 资源文件与前端构建.properties文件的编码问题我已经在 3.1 提过这里补充一点如果你的项目里有messages_zh_CN.properties这类国际化文件它里面的中文在构建后如果显示成问号多半是 Maven 的native2ascii环节没配好或者 JDK 版本变化导致默认行为改了。前端资源同理。Sass、Less 这类预处理器编译时也会读文件如果编译命令里没指定编码输出的 CSS 里中文内容就可能变形。Vue 的 SFC 单文件组件在构建时如果注释里有中文构建日志乱码也是同一类问题。核心思路完全一样找到读取源文件的程序显式告诉它编码。还有一个容易被忽略的场景是 CSV 导出。Java 写出的 UTF-8 CSV 用 Excel 打开常常乱码因为 Excel 在中国区默认按 GBK 解码。解决方式是在写文件时先写一个 UTF-8 BOMEF BB BF作为开头Excel 看到 BOM 就会自动按 UTF-8 处理。这个和构建没关系但原理是一样的——你要主动告诉读取端该用什么编码。6.3 常见场景对照表现象最可能的原因优先排查方向 重复出现用错误字符集解码 UTF-8 字节输出端与读取端编码是否一致锟斤拷UTF-8 与 GBK 之间发生了两次错误转码中间环节是否有强制转码英文字符也变乱码符号字节流被整体错位解读查管道、重定向、压缩解压环节中文显示为问号?编码时目标字符集不包含该字符查写出端的字符集设置中文显示为空心方块字体缺少对应字形换字体或配置 Fallback font只有部分字符乱混合编码文件本身不统一检查文件是否被部分编辑保存过本地正常 CI 乱服务器 locale 未设置为 UTF-8设置LANGC.UTF-8这张表我用了很久基本覆盖了九成以上的场景。剩下那一成通常是多个原因叠加或者数据在写入磁盘时就已经损坏了——那种情况任何配置都救不回来只能从源头重新生成。7. 排查手册与踩坑记录前面把原理和配置都铺开了这一节我把它们压成可以照着执行的流程。我处理这类问题的习惯是自上而下、由外到内按固定顺序走一遍而不是东改一处西改一处。7.1 五分钟定位流程第一步确认乱码形态。截个图看清是、?、锟斤拷还是方块。这一步十秒但决定了后面所有方向的正确性。第二步判断范围。是只有 Build Output 乱还是整个控制台、日志、文件全都乱如果只有一处乱问题就在那一处对应的环节如果所有中文都乱那大概率是 IDEA 进程级别的编码问题直接从 vmoptions 下手。第三步做对照实验。在命令行里手动执行一次编译把输出重定向到文件然后用十六进制工具看字节。这一步能直接告诉你字节流本身是好的还是坏的。如果是好的问题就在 IDEA 读取端如果是坏的问题在 javac 输出端。第四步改一处验证一处。这也改那也改最后就算好了你也不知道是哪一处起的作用下一个项目还得重来。第五步记录到项目文档。把最终生效的配置写进 README 或者团队文档尤其是 Maven/Gradle 里那些容易漏的配置项。这个动作的价值会在半年后体现出来。7.2 高频问题速查表问题排查方向处理方式改了 vmoptions 没效果是否完全退出 IDEA从托盘退出确认进程结束再启动只有中文报错乱英文正常诊断信息语言与 stdout 编码加-Dstdout.encodingUTF-8命令行正常 IDEA 乱IDEA 的读取端设置查 File Encodings 与字体IDEA 正常命令行乱终端代码页与 localeWindows 上chcp 65001Linux 上设 locale源文件中文常量报错javac 未指定编码加-encoding UTF-8编译参数子模块乱主模块正常编码配置未继承在父工程统一配置升级 JDK 后突然乱默认编码语义变化显式指定 stdout/stderr 编码输出里出现大量?写出端字符集不支持中文检查目标字符集是否真的是 UTF-87.3 几条用教训换来的经验第一条永远不要依赖默认值。我踩过的最大的坑就是相信新版本 JDK 已经默认 UTF-8 了所以不用配。结果 stdout 那一层还是跟着系统走白白浪费了一个下午。显式配置的成本是几行代码收益是任何机器上都能复现的行为。第二条Windows 上的代码页是个隐形变量。你在 PowerShell 里跑一条命令和你在 IDEA 的 Terminal 面板里跑同一条命令结果可能完全不同因为两者的代码页设置不一样。排查时如果发现命令一样结果不一样先去查chcp输出的是什么。第三条不要用修改文件内容的方式去修乱码。我见过有人把乱码的 properties 文件用记事本另存为 UTF-8结果文件内容真的被改成了乱码字符原来的中文彻底丢了。正确的做法是改读取方式而不是改文件。第四条git diff 是最好的验证工具。你改完编码设置之后如果git status显示一大批文件被修改说明有文件被真的重新编码了赶紧回退。真正的修复不应该改动任何文件内容。第五条日志乱码和编译乱码要分开治。这两个问题的链路完全不同前者是运行时的输出后者是编译时的诊断信息。虽然解决思路相似但配置位置不一样别把运行配置里的编码参数往编译器设置里填。最后分享一个我自己觉得最省事的习惯给所有新项目建一个编码检查脚本。Maven 项目就检查父 POM 里那三个 encoding 属性Gradle 项目就检查gradle.properties和build.gradle里的那两处配置IDEA 项目就检查.idea/encodings.xml文件是否存在且内容为 UTF-8。这个脚本我放在 CI 的第一步构建开始前先跑一遍报错就说明有人引入了编码不一致的配置。团队里用了两年编码相关的工单基本上清零了。至于我个人最真实的体会是这个问题的难点从来不在怎么配而在配哪一层。配置文件就那么几行十分钟就能背下来但能不能在十分钟内判断出问题出在哪一段链路上才是区分熟练和生疏的地方。所以下次再看到先别急着改设置先问问自己这段字节是谁写出来的又是谁读进去的。