1. 初见乱码控制台花成一片文件却静悄悄1.1 第一次在 Windows 上启动 Tomcat 的经典场面Tomcat 在 Windows 本地启动日志中文乱码这大概是每个刚接触 JavaWeb 开发的人都绕不开的“成人礼”。我第一次碰到时也很懵双击startup.bat控制台窗口里刷出大量启动信息英文、数字、日期都正常但凡是中文的地方全变成了“鍒濆鍖栦腑”“涓夋捣”这种看着完全不像正常汉字的字符。第一反应是“是不是系统字体问题”“是不是 Java 环境装坏了”然后打开浏览器一顿搜试了七八种方法有的完全无效有的当时好了隔天又乱。后来症状更诡异同一个程序输出的日志控制台里乱码但打开 Tomcat 的logs目录找到catalina.2025-xx-xx.log用记事本打开一看里面的中文居然是完好的。同一个时间点同一批输出一个地方乱一个地方不乱这已经不是“运气不好”能解释的了。如果你现在正遇到这个场景先别急着改一堆配置冷静想一个问题乱码到底发生在哪一层1.2 动手前先分清是哪一类“中文乱码”我处理过不少类似问题经验是先按乱码出现的位置分三类不然很容易把水搅浑只有控制台窗口乱码日志文件正常这是最常见的情况根因基本是 Tomcat 日志框架往控制台输出的编码和 Windows 控制台默认的解码方式不一致。日志文件也乱码或者在某个编辑器里打开乱码文件本身的字节编码可能没有问题是编辑器用错了编码在“翻译”它。Tomcat 自带的启动日志正常但部署的应用比如 Web 项目自己打印的中文乱码这通常要查项目的日志框架比如 Logback、Log4j2 的编码配置跟 Tomcat 的logging.properties没有直接关系。这三类问题表面都一样是“中文变乱码”但修法完全不同。我最怕的就是有人不管三七二十一先把系统的区域设置改成 UTF-8再把 Tomcat 的编码改一遍最后项目日志也改一遍。一通操作下来乱码可能确实没了但你根本不知道是哪个设置起的作用换一台机器、换一个项目照样踩坑。这篇文章我先讲清楚最常见的第一类问题也就是“控制台乱码、文件正常”的完整修复链路再把另外两类容易误诊的“变种乱码”单独拉出来说。内容基于我自己的实操经验配置步骤都是可以直接抄的。2. 乱码根因Windows 代码页、Java 字符集与 Tomcat Handler 的三角关系2.1 三个“当事人”的默认值要真正解决乱码不是背一个“改 ConsoleHandler 编码为 GBK”的口诀就完事你得先知道中文 Windows、Java 运行时、Tomcat 日志框架这三方各用什么编码。我把默认值整理成一张表对象默认字符集/代码页说明Windows 中文版 cmd 控制台GBK代码页 936CP936中文 Windows 的 conhost 默认用 GBK 解码控制台输出的字节Java 运行时file.encoding跟随系统 locale中文 Windows 下通常是 GBKSystem.out、System.err的底层默认字符集受它影响Tomcat JULI 日志 Handler常见配置为 UTF-8Tomcat 的日志框架叫 Juli配置文件在conf/logging.properties里面的 FileHandler 和 ConsoleHandler 都可能显式或默认指定为 UTF-8看到这张表问题就浮出水面了日志框架按 UTF-8 编码把中文变成一串字节窗口按 GBK 去解码两边对不上。打个比方发件人用 UTF-8 字典把“你好”翻译成一串字节寄出去收件人拿着 GBK 字典去查查出来的当然不是“你好”而是“浣犲ソ”这种毫无逻辑的组合。2.2 为什么同一份日志文件正常控制台乱码Tomcat 的日志不是只有一个出口。它用 Juli 这个基于java.util.logging扩展的框架管理日志在conf/logging.properties里注册了多种 HandlerFileHandler 把日志写进logs目录下的文件ConsoleHandler 把日志输出到控制台。两个 Handler 各自有独立的encoding配置。典型配置里FileHandler 和 ConsoleHandler 都按 UTF-8 输出那么文件那边UTF-8 字节被原样写进了catalina.YYYY-MM-DD.log现代记事本、VS Code、Notepad 都支持自动检测 UTF-8所以你打开文件看到的中文是正常的。控制台那边UTF-8 字节被输出到 Windows 控制台而 conhost 默认按 GBK 解码一个 UTF-8 的中文字符通常占 3 个字节GBK 一个汉字占 2 个字节两者错位后就是一串看着像加密一样的汉字组合。也就是说日志文件里的数据本身没有坏控制台显示的乱码也不是“丢字符”而是两边解码规则不匹配。理解了这一点就不会再傻乎乎地认为“文件乱码就得改文件编码”了。2.3 乱码的“长相”能当线索用乱码字符长什么样其实能帮你反向判断是哪一侧的编码出了问题。这个技巧在排查时特别值钱一段正确的 UTF-8 中文如果被 Windows 控制台按 GBK 解码常出现“鍒濆鍖栦腑”“涓夋捣”“鐧诲綍”这类字——每个字你都认识但组合起来完全不像人话。一段被错误存储或者被错误解码的 GBK 字节如果拿 UTF-8 去解更容易出现“”这种黑色问号替换符或者“寮€濮嬪垵濮嬪寲”这种一半像中文一半不像的杂糅字符。看到“鍒”这种偏旁基本可以锁定是“UTF-8 字节被当 GBK 读”。这时候你的修复方向就是把控制台出口的字节改成 GBK或者让控制台改用 UTF-8 来读二者选一即可。后面两章我会分别讲这两条路怎么走。2.4 顺带提醒不同 Tomcat 版本的 Handler 名称不一样改配置前一定要先确认你用的 Tomcat 版本因为logging.properties里 Handler 的命名前缀不是一个版本用到老的Tomcat 8 及更早版本常见文件名是1catalina.org.apache.juli.FileHandler。Tomcat 9/10 及更新版本默认换成了1catalina.org.apache.juli.AsyncFileHandler。别小看这个差别。我见过有人照着 Tomcat 8 的教程在 Tomcat 9 的配置文件里加了 FileHandler 的编码设置结果日志还是乱码因为配置文件里根本没有注册这个 Handler加的那行配置根本没被加载。动手前先type conf\logging.properties看一眼实际内容比什么都强。3. 主修复把 ConsoleHandler 编码拧回 GBK3.1 修改 logging.properties 的正确姿势第一类乱码控制台乱码、文件正常的修复思路很简单既然 Windows 中文控制台是“GBK 的收件人”那我们就让 Tomcat 输出到控制台时按 GBK 编码。具体操作如下先停掉 Tomcat建议用shutdown.bat正常关闭别直接叉掉窗口。打开%CATALINA_BASE%\conf\logging.properties。注意是CATALINA_BASE不是CATALINA_HOME默认情况下二者多半一致但在多实例或 IDE 里启动时可能不同后面会展开说。找到handlers那一行确认里面注册了java.util.logging.ConsoleHandler。常见写法是handlers 1catalina.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler在配置里加上或修改这一行java.util.logging.ConsoleHandler.encoding GBK保存文件重启 Tomcat看控制台输出。完整修改后的关键段大致长这样java.util.logging.ConsoleHandler.level FINE java.util.logging.ConsoleHandler.encoding GBK如果你担心手误也可以把整个 ConsoleHandler 段单独写清楚。有些版本默认没有encoding这一行有些版本写的是UTF-8你只需要把值改成GBK即可。编码名建议大写Windows 平台的 JVM 对 GBK、gbk、GB2312 都有兼容处理但统一大写更稳。3.2 修改后还乱先检查三个容易被忽略的点改了配置、重启容器控制台还是乱码别急我从现场经验里提炼了三个高频翻车点第一改错了 BASE。如果你在 IDEA 或者其他 IDE 里以“外部工具”方式启动过 Tomcat然后又在命令行用startup.bat启动两份实例的%CATALINA_BASE%可能完全不是一个目录。启动时可以先在那个窗口里执行echo %CATALINA_BASE%再确认你改的conf\logging.properties是不是这个目录下的。如果不一致你改的很可能是个“从未被加载”的副本。第二被JAVA_OPTS里的配置覆盖。有人会在setenv.bat或系统环境变量里加过-Djava.util.logging.config.file其它路径这个参数会强制 JVM 使用指定路径的日志配置conf\logging.properties就形同虚设。排查时可以查看启动窗口里的命令行参数或者搜索一下 setenv.bat 里有没有类似设置。第三没真正重启。开发时用 IDE 里的热部署往往只重启了应用没有重启容器。Tomcat 的日志 Handler 在启动早期就初始化了只重启 Web 应用不会重新加载logging.properties。必须把 Tomcat 整个停掉再启动配置才能生效。3.3 文件日志要不要跟着改成 GBK有人可能想“既然控制台改 GBK 了文件也改成 GBK 吧统一了不更省事”我的建议是不要。理由很简单日志文件是要长期保存、跨机器传输、交给日志采集系统解析的现代日志采集链路默认都是 UTF-8。你把文件编码改成 GBK虽然在这台 Windows 机器上看着舒服一旦文件被同步到 Linux 服务器或者被某个采集 agent 按 UTF-8 解析轻则中文乱码重则整个文件无法被正确切分。控制台只是给人临时看的GBK 没问题文件是要给机器和未来的你看的保持 UTF-8 才是长久之计。如果你确实因为某些旧工具链必须用 GBK可以单独改# Tomcat 8 1catalina.org.apache.juli.FileHandler.encoding GBK # Tomcat 9/10 1catalina.org.apache.juli.AsyncFileHandler.encoding GBK但我始终认为这是不必要的妥协没必要为了一个“控制台显示”去污染整个日志链路。4. 另一条路把 Windows 控制台切到 UTF-84.1 chcp 65001 的临时切换与兼容性问题和第 3 章相反如果你不想动 Tomcat 配置也可以反过来让 Windows 控制台去适应 UTF-8。在 cmd 里执行chcp 65001执行后当前控制台会话的代码页会变成 65001也就是 UTF-8。这时再启动 TomcatConsoleHandler 按 UTF-8 输出的字节就能被正确显示了。但这里有个现实问题Tomcat 的startup.bat默认会新开一个窗口去跑catalina.bat你当前窗口执行chcp 65001影响不到那个新窗口。想让新窗口也生效可以把chcp 65001写进setenv.bat的顶部或者写一个自定义启动脚本来包装echo off chcp 65001 call catalina.bat start实测下来这条路线在 Windows 10 较新版本上表现还行但并非没有代价。chcp 65001后控制台里如果输出一些带 ANSI 颜色控制符的日志某些版本的 conhost 渲染会异常Java 进程读取中文路径参数时也可能出现莫名其妙的乱码。另外PowerShell 的默认代码页和 cmd 不完全一样二者切换时又容易出幺蛾子。所以这个方案更适合“临时看一眼”不适合作为长期配置。4.2 系统级 UTF-8 开关能不开就不开还有一个经常被搜到的方案在“控制面板 → 区域 → 管理 → 更改系统区域设置”里勾选“Beta 版使用 Unicode UTF-8 提供全球语言支持”然后重启系统。开启后整个系统的 ANSI 代码页都会变成 UTF-8Tomcat 控制台乱码确实能消失。但我要劝你谨慎。这个开关影响的是整个操作系统的非 Unicode 程序编码行为很多老的 Windows 软件、中文版安装包、老旧文本编辑器都会跟着出问题。为了一个 Tomcat 日志乱码去动系统级设置相当于“因为客厅灯泡坏了把总电闸拉了”后面可能引发更麻烦的连锁反应。我处理过一起案例某人开了这个开关后某老旧客户端软件的中文界面全部变成乱码最后只能关掉开关而 Tomcat 乱码依然没解决白折腾半天。4.3 为什么我不建议动 file.encoding网上很多老教程会告诉你在setenv.bat里加set JAVA_OPTS%JAVA_OPTS% -Dfile.encodingUTF-8然后重启。这个方法我之前也试过不能说完全没用但非常容易造成“假解决”。这个参数主要影响的是 Java 运行时默认字符集比如System.out这类流最初用哪个字符集构建。而 Juli 的 Handler 编码是自身配置的不一定会被这个参数覆盖。你加了之后可能某几个环节的中文不乱码了但与此同时所有依赖“默认字符集”做字符串转换的老代码都可能改变行为出现新的隐性问题。更麻烦的是这类改动会让排查链变得更长。你一边改了 file.encoding一边改了 logging.properties还顺手改了几个 IDE 设置最终乱码消失得不明不白。我的原则很简单一个变量一个变量地改改完立刻验证验证通过就不再叠加其他方案。这样才能形成可复现、可传授的经验而不是靠玄学修 bug。5. 三种容易被误诊的“变种乱码”5.1 文件打开乱码编辑器没有认对 UTF-8有人改完控制台却发现日志文件用某种编辑器打开还是乱码于是怀疑 FileHandler 编码也有问题。这时候先别急着改配置大概率是“看文件的眼睛”错了。比如 Win7 时代自带的记事本默认按 ANSI/GBK 解码文本文件你把 UTF-8 编码的日志拖进去必然乱码。Windows 10 之后的记事本自动检测 UTF-8 的能力已经很强所以现代系统上比较少见了但如果你用的是某些老旧的文本编辑器或者直接把文件拖进了总按 GBK 打开的软件就会遇到这种“文件本身完全正常只是打开方式不对”的假乱码。验证方法很简单用 VS Code 或 Notepad 打开手动切换编码到 UTF-8。VS Code 右下角会显示当前文件的编码点击后选择“Reopen with Encoding → UTF-8”中文立刻变正常的话日志文件本身没有坏不需要动 Tomcat 任何配置。5.2 应用自己输出的日志乱码Logback/Log4j2 有自己的编码Tomcat 的logging.properties只管理 Juli 框架的日志输出。如果你的 Web 项目里引入了 Spring 框架、业务代码用 Logback 或 Log4j2 打印日志这些应用的日志完全可能不走 Juli而是走自己的日志框架。它们的中文乱码跟 Tomcat 的 ConsoleHandler 没有半毛钱关系。排查方法依然是“先看文件、再看框架配置”如果日志文件用 UTF-8 打开正常用 GBK 打开乱码说明文件写入时用的是 UTF-8那问题可能出在控制台展示环节需要去看日志框架的控制台输出编码配置。如果日志文件本身用 UTF-8 打开也是乱码说明文件写入时的编码就不是 UTF-8要改的是应用日志框架的文件 appender 编码。拿 Logback 举例控制台输出中文化一般要求 encoder 里显式指定字符集appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder charsetUTF-8 pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %logger{36} - %msg%n/pattern /encoder /appenderLog4j2 也类似在 PatternLayout 或文件 RollingFile appender 上设置 charset。这些是应用层的事不能拿 Tomcat 的配置去顶。5.3 IDEA 内置终端里的乱码根子也在代码页很多开发者在 IDEA 的 Terminal 面板里用命令行启动 Tomcat遇到乱码后第一反应是改 IDEA 的 Settings → File Encodings把 Global Encoding、Project Encoding、Properties Files 全部设成 UTF-8。但你会发现有时改完了 IDEA 自带的控制台比如 Tomcat 插件输出正常了内置 Terminal 里还是乱码。原因在于 IDEA 的 Terminal 本质上是嵌了一个命令行环境底层还是 Windows 的 conhost 或 Windows Terminal 那套逻辑控制台代码页的问题依然存在。所以你在内置 Terminal 里执行chcp看到的结果和外部 cmd 基本是一样的。有效的做法有三条把第 3 章讲的 ConsoleHandler 改成 GBK同时确保 IDEA 里启动 Tomcat 用的也是同一个%CATALINA_BASE%。在 IDEA 的 Terminal 设置里把 Shell path 改为cmd.exe并指定一个初始化命令执行chcp 65001具体位置在 Settings → Tools → Terminal。干脆不折腾内置终端统一用外部 cmd 或 Windows Terminal 启动 Tomcat环境更干净日志也更完整。5.4 复现排查的最小步骤如果你在现场被这个问题卡住可以从这三条命令开始取证每一步输出都拍下来很快就能定位chcp看当前控制台代码页936 代表 GBK65001 代表 UTF-8。java -XshowSettings:properties -version 21 | findstr /i file.encoding看 JVM 启动时的默认文件编码。type %CATALINA_BASE%\conf\logging.properties | findstr /i encoding看当前 Tomcat 日志 Handler 的编码设置注意 Handler 名称前缀和实际注册的 handler 是否匹配。这三条命令的信息再配合“控制台乱还是文件乱”这个现象基本能把 80% 的乱码问题定位到具体环节。6. 一次到位我的标准排查清单与经验6.1 从现象到根因的判定表我把多年排查经验压缩成一张判定表你遇到乱码时直接对照现象常见根因处理动作控制台乱码文件正常ConsoleHandler 编码与 Windows 代码页不一致改 ConsoleHandler.encoding GBK或 chcp 65001文件用旧编辑器打开乱码UTF-8 打开正常编辑器编码识别问题换编辑器重新按 UTF-8 打开文件本身乱码UTF-8/GBK 都读不出正常中文文件写入编码设置错误检查 FileHandler 编码、应用日志框架编码只有应用业务日志乱码Logback/Log4j2 编码配置问题在应用日志框架里显式配置 charsetIDEA 内置终端乱码外部 cmd 正常终端代码页与输出编码不匹配设置终端启动时 chcp或改 ConsoleHandler多实例 Tomcat 时改了配置不生效CATALINA_BASE 改错先 echo %CATALINA_BASE%确认配置路径这张表不能保证覆盖所有奇葩场景但能帮你在最短时间内把问题缩小到一个可控范围。6.2 我的标准处理顺序我的习惯是从影响面最小的方案开始一次只改一个地方。具体流程是先确认logs目录下的文件是否正常确认“控制台乱、文件正常”这个基础现象再执行chcp看代码页然后改logging.properties里的 ConsoleHandler 编码为 GBK最后完整重启 Tomcat 验证。如果还乱才去看setenv.bat有没有覆盖配置、是不是多实例、IDE 终端是不是特殊环境。这个顺序执行下来大部分问题在第二步就已经解决了。没有解决的时候也不会把现场搞得更乱因为每一步都有明确记录可以回退到之前的状态继续排查。6.3 几个我踩过的坑提前给你排掉第一不要三管齐下。曾经有个项目同事同时改了系统区域设置、Tomcat ConsoleHandler、应用的 logback charset乱码确实没了但之后日志采集平台上报的数据出现大量编码错误回查时根本不知道哪步改错了。排错必须一条一条来。第二重启 Tomcat 之前顺手把旧日志清一下或归档。旧日志文件是旧编码环境写出来的你重启后看新日志如果窗口里混入了旧内容会干扰判断。养成“启动前清空 logs 下当天的旧文件”这个习惯能省很多事。第三不要迷信某一个版本的配置。你的 Tomcat 可能是 8.5可能是 10也可能是嵌入式启动比如 Spring Boot 内嵌 Tomcat。嵌入式场景下conf/logging.properties甚至可能不存在乱码问题的处理路径完全不同。下手前先确认你的 Tomcat 到底是不是传统独立部署再看配置。第四如果你只是临时需要看一次日志可以用chcp 65001救急但别把它写进全局启动脚本除非你确认整个团队用的 Windows 版本都能稳定支持。长期方案永远优先选择“让日志输出适配目标终端”而不是让终端去适配所有日志。Tomcat 中文乱码这件事说透了就是一个“编码对齐”的小问题。你只要能把“谁按什么编码写、谁按什么编码读”这两件事盘清楚再遇到任何类似乱码都不会慌。配置文件就摆在conf\logging.properties里所有东西都是可控的。