1. 先说结论乱码的本质是编码链断裂做 Java Web 开发的朋友几乎没人能避开这个经典问题在 IntelliJ IDEA 里启动 TomcatConsole 窗口输出一屏乱码中文全部变成锟斤拷烫烫烫或者方块问号。更折磨人的是同一个项目在同事电脑上运行正常到自己这里就乱码今天还好好的换了个 JDK 版本或者 Tomcat 版本又开始乱。如果你正被这个问题搞得焦头烂额这篇文章就是给你准备的。我先给结论Tomcat 日志乱码不是 bug而是编码链断裂。一行日志从 Tomcat 打印到 IDEA 控制台至少经过三个环节Tomcat 内部用某种编码生成日志字符串交到 JVM 标准输出变成字节流IDEA 拿到字节流后用另一种编码解码并渲染显示。中间任何两个环节使用的字符集不一致屏幕上就会出乱码。而中文 Windows 系统天然就是重灾区系统 ANSI 编码默认是 GBK代码页 936Tomcat 8.5 及以上版本默认用 UTF-8 写日志一个写 UTF-8、一个读 GBK字节对不上不乱码才怪。这篇文章不堆砌理论直接给出我实际项目里验证过的完整方案覆盖 IDEA 自身编码设置、Tomcat 运行配置、Tomcat 的 logging 配置、Windows 启动脚本以及一套查错排障链路。无论你是刚在 IDEA 里配好 Tomcat 的新手还是被 Spring Boot 内嵌日志折磨过的老开发按顺序操作一遍能解决绝大多数情况下的乱码问题。1.1 一行日志从 Tomcat 到 IDEA 到底经历了几道关用大白话解释Tomcat 写了一封UTF-8 信IDEA 却拿GBK 字典去翻译翻出来的自然不是人话。反过来如果 Tomcat 输出 GBKIDEA 拿 UTF-8 去解同样翻车。具体到 IntelliJ IDEA 启动 Tomcat 的场景链条是这样的Tomcat 的 JULI 日志系统通过ConsoleHandler把日志写到标准输出stdout/stderrTomcat 子进程 JVM 按它的默认字符集把字符串编码成字节流这个默认值由file.encoding系统属性决定IDEA 作为父进程读取子进程标准输出按它自身 JVM 的file.encoding解码这些字节流解码后的字符串进入 Console 控件再由控制台组件渲染出字符。乱码可能发生在第 2 步写出的字节流编码不对、第 3 步IDEA 解码口径不对、或者第 4 步控制台渲染编码不对。网上很多教程只说改一个地方往往只覆盖了其中一环所以才会出现有的人照着改有用、有的人完全没用的差异。1.2 为什么同样的项目有的电脑正常有的电脑乱码编码链路上的变量实在太多Windows 系统区域中文简体、繁体、英文、JDK 版本JDK 8 默认 GBKJDK 18 默认 UTF-8、Tomcat 版本7 和 8.5 的默认日志编码不同、IDEA 版本的默认行为、以及你是否曾经改过 vmoptions。任意一两个因素组合不同乱码表现就完全不一样。所以我从来不建议上来就抄别人的神仙配置先花五分钟判断自己属于哪类场景再对症处理这才是高效率的路径。2. 动手之前先判断你的乱码属于哪一种我见过太多人一看到乱码就冲去改logging.properties改完没用又重装 Tomcat最后问题依旧。根因是没先定位病灶在链路中的哪一环。源头不同解决方案完全不同乱改了只会浪费时间。2.1 四种最常见的乱码场景场景典型表现主要病灶A. IDEA 控制台里的 Tomcat 启动日志乱码Run 窗口中 Tomcat 启动横幅、部署提示、端口信息全是乱码IDEA 读取子进程输出时的解码编码B. 应用自身业务日志乱码自己代码里System.out.println或 slf4j 输出的中文乱应用进程 JVM 的file.encodingC. Tomcat 磁盘日志文件乱码用编辑器打开logs/下catalina.*.log、localhost.*.log内容是乱的FileHandler.encoding写出编码D. Spring Boot 内嵌 Tomcat 日志乱码跑 Spring Boot 应用时启动日志乱但独立 Tomcat 正常Logback / Log4j2 的 appender charset看一下自己的现象对应哪种类型你就大概知道该往哪个方向查了。接下来用三步验证法把病灶锁定得更精确。2.2 三步快速定位病灶第一步打开文件确认。进入 Tomcat 安装目录的logs文件夹找到当天的catalina.YYYY-MM-DD.log用 IDEA 或 VS Code 打开。观察编辑器右下角自动识别的编码如果文件按 UTF-8 识别后内容正常说明 Tomcat 写文件没问题病灶在 IDEA 控制台的读取侧如果文件切到 GBK 才正常说明写出端用的就是 GBK要回去改 Tomcat 的日志写出编码。第二步看乱码特征。把乱码文字复制出来看看锟斤拷是 UTF-8 字节被 GBK 误解码的经典产物烫烫烫多见于内存未初始化的场景Java 里少见但有人遇到过大量问号和方块说明字符在某一步已经被替换成了 ASCII 替代符信息已经丢失。这种情况要从更早的环节查起死磕显示端是没用的。第三步打印 JVM 默认编码。在项目里临时加一行System.out.println(Charset.defaultCharset().name());启动后看控制台输出。这一行能直接告诉你应用进程的默认字符集到底是 UTF-8 还是 GBK顺便验证你的运行配置改动有没有真正生效。这个方法简单粗暴是我排查时最常用的第一步。3. 第一套方案在 IDEA 侧统一编码口径IDEA 侧配置是整套方案的基座。如果 IDEA 读取子进程输出的口径不对Tomcat 那边就算全改成 UTF-8控制台该乱还是乱。下面按顺序给出完整步骤每一步都附上理由免得你改完不知道为啥有效。3.1 File Encodings 里的三处编码要一起改打开SettingsmacOS 上是Preferences→Editor → File Encodings把下面这些全部统一为 UTF-8Global Encoding全局默认Project Encoding当前工程Default encoding for properties filesproperties 文件默认编码有Console相关下拉选项的版本把控制台默认编码也设成 UTF-8properties 文件建议勾选Transparent native-to-ascii conversion让 properties 里的中文以 Unicode 转义形式存储避免运行时读取乱码这一步的作用是给 IDEA 的编辑器、文件系统和一部分编译运行组件一个统一的 UTF-8 上下文相当于打好地基。但注意它只管编辑器读写文件管不到控制台解码所以必须配合下一步来做。3.2 最关键的一步修改 IDEA 自身的 VM 参数菜单栏Help → Edit Custom VM Options...在打开的 vmoptions 文件末尾追加一行-Dfile.encodingUTF-8保存后重启 IDEA这个参数才能生效。为什么这一步最关键因为 IDEA 本身是一个跑在 JVM 上的 Java 程序。控制台窗口读取 Tomcat 子进程的标准输出时IDEA 会按照它自己 JVM 的file.encoding来解码字节流。你在 File Encodings 里改的是文本编辑器读写编码那些设置管不到控制台解码。只有让 IDEA 整个 JVM 的默认字符集变成 UTF-8它读取 Tomcat 输出时才会用 UTF-8 解码控制台乱码才有可能真正消失。提示Help → Edit Custom VM Options保存的是用户级 vmoptionsWindows 下对应idea64.exe.vmoptionsmacOS/Linux 下对应idea.vmoptions优先级高于安装目录里的默认配置。如果之前用安装包或外部工具改过 vmoptions注意别改重复以最后写入的配置为准。3.3 改完这两个地方还乱说明问题不在读取端如果你已经把 File Encodings 三处和 IDEA VM 参数都改了也重启了控制台还是乱码那基本可以判定问题的核心在 Tomcat 子进程的写端而不是 IDEA 的读端。前面说过链路要两头对齐。IDEA 这边解决的是读接下来要解决写也就是第四节的运行配置参数。4. 第二套方案在 Tomcat 运行配置里注入编码参数在 IDEA 里跑 Tomcat本质上是 IDEA 帮你执行 Tomcat 启动脚本Tomcat 是独立子进程。子进程 JVM 的默认字符集不会因为 IDEA 改了 vmoptions 就自动同步它由启动时的命令行参数和环境决定。所以我们必须显式告诉它用 UTF-8 来编码输出。4.1 运行配置的 VM options 具体填什么操作路径Run → Edit Configurations...选中你的Tomcat ServerLocal配置在Server标签页下方找到VM options输入框填入-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8-Dfile.encoding负责字符流读写控制台输出、日志写入-Dsun.jnu.encoding负责 JVM 解析文件路径和文件名的编码。如果你的项目路径带中文或者某个资源文件找不到、读取异常后一个参数很可能就是元凶。两个一起写最稳妥。填完点击 Apply重新启动 Tomcat。这一步对应用自身输出乱码和控制台乱码通常立竿见影——因为整个子进程的字符输出口径已经被摆正了。4.2 为什么 IDEA 全局设置了这里还要再填一遍这是新手最容易困惑的地方。我们把 IDEA 比作翻译官Tomcat 比作写信人。光给翻译官换新的解码字典IDEA VM 参数写信人手上还是旧的信纸和墨水子进程默认 GBK写出来的信内容本身就是按 GBK 编码的字节流翻译官拿 UTF-8 去翻译照样看不懂。只有两头统一让 Tomcat 子进程用 UTF-8 写、IDEA 用 UTF-8 读控制台里的中文才能正常显示。如果你把两处都设成 UTF-8 后Windows 的 CMD 窗口直接敲catalina run看到的是正常中文但 IDEA 控制台还是乱码那问题就集中在 IDEA 读取端回去重点检查 3.2 的 VM 参数是否真的被加载了。4.3 别忘了 JDK 版本这个隐藏变量JDK 8 及更早版本在中文 Windows 上file.encoding默认取系统区域设置的 ANSI 码也就是 GBK。JDK 18 开始JEP 400默认改成 UTF-8JVM 不再依赖系统区域。这带来一个很多人会看懵的现象用 JDK 8 Tomcat 8.5 及以上两边的默认编码都踩在旧体系上乱码概率很高必须显式指定-Dfile.encodingUTF-8用 JDK 17/21Tomcat 侧默认 UTF-8通常只需要把 IDEA 读取端搞定乱码就没了反过来老项目故意依赖 GBK 读写文件升到 JDK 17 后可能出现新乱码这时候反而是要去显式指定 GBK 或者改造代码不要盲目追新。这也是我反复叮嘱不要盲抄配置的原因网上 80% 的乱码解决方案都是基于 JDK 8 时代写的到了 JDK 17/21 环境很多步骤其实可以省略但整套跑一遍也不会造成额外问题安全起见照着做就好。4.4 Spring Boot 内嵌 Tomcat 是另一套日志体系如果你用的不是独立下载的 Tomcat而是spring-boot-starter-web里内嵌的 Tomcat情况要单独处理内嵌 Tomcat 只是应用里的一个库它的日志输出走的是 LogbackSpring Boot 默认或者 Log4j2跟 Tomcat 自己的 JULI 没有关系。这时候去改 Tomcat 的logging.properties完全没用得去管日志框架。最简单、也最推荐的做法在logback-spring.xml的 console appender 里显式指定 charsetappender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder charsetUTF-8/charset pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appenderLogback 的 ConsoleAppender 在不指定 charset 时会使用System.out对应的编码中文 Windows 下极容易落到 GBK。加一行charsetUTF-8/charset配合运行时配置里的-Dfile.encodingUTF-8Spring Boot 项目在 IDEA 里的中文输出基本就正常了。Log4j2 用户同理在 Console appender 的PatternLayout属性里指定charsetUTF-8。顺带提一句如果你是用 Maven 的spring-boot:run启动而不是 IDEA 的 Run Dashboard 启动注意 spring-boot-maven-plugin 会 fork 一个子进程同样需要把编码参数传给这个 fork 出来的 JVM否则控制台该乱还是乱。Maven 配置里可以加-Dspring-boot.run.jvmArguments-Dfile.encodingUTF-8或在环境变量MAVEN_OPTS里补。5. 第三套方案从 Tomcat 自身日志通道下手IDEA 侧和运行配置这两个入口处理完控制台基本干净了。但有些人的乱码不只出现在控制台还出现在 Tomcat 的磁盘日志文件里——打开catalina.2025-xx-xx.log满屏乱码。这就必须碰 Tomcat 自己的日志写出设置了。5.1 logging.properties 里管着两种输出Tomcat 日志配置文件在$CATALINA_BASE/conf/logging.propertiesCATALINA_BASE 通常就是 Tomcat 安装目录。两个核心属性java.util.logging.ConsoleHandler.encoding UTF-8 java.util.logging.FileHandler.encoding UTF-8ConsoleHandler管控制台输出影响的是 IDEA 里那一部分 Tomcat 自身日志FileHandler管logs/目录下的磁盘文件影响你打开文件看到的内容。Tomcat 8.5/9/10/11 默认值就是 UTF-8但我们经常遇到一种情况配置文件里写着UTF-8实际写出来却是乱码。这时候要怀疑是否有启动脚本或环境变量覆盖了 JVM 默认编码比如setenv.bat里写了-Dfile.encodingGBK——一旦 JVM 默认编码变了没显式指定 encoding 的 Handler 会跟随 JVM 默认值走配置文件写了 UTF-8 也不生效。5.2 不想纠结就注释掉让编码跟着 JVM 走如果你实在分不清该设 UTF-8 还是 GBK有个很省心的做法把ConsoleHandler.encoding和FileHandler.encoding这两行注释掉让它们使用 JVM 默认编码。然后你在 VM options 或 setenv 脚本里把file.encoding明确设成 UTF-8。这时候整个逻辑就变成JVM 默认字符集 UTF-8Handler 不显式指定 → 自动跟随 JVM 默认 UTF-8控制台输出和文件输出的口径完全一致不再有配置文件和实际行为不一致的诡异情况。这一招我经常用在老项目的迁移场景简单可靠特别适合不确定环境里有没有历史遗留配置的场合。5.3 独立启动时的正解setenv.bat不要直接改 catalina.bat如果你不是从 IDEA 启动而是直接在 Windows 命令行或服务里启动 Tomcat就要在启动脚本里补参数。Tomcat 的机制是catalina.bat启动时会自动寻找同目录下的setenv.bat存在就执行Linux 对应setenv.sh。因此正确的做法是新建/编辑bin/setenv.batset JAVA_OPTS%JAVA_OPTS% -Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8Linux 环境对应setenv.shexport JAVA_OPTS$JAVA_OPTS -Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8为什么强烈不建议直接改catalina.bat因为 Tomcat 升级或重装时catalina.bat一定会被官方文件覆盖你的修改全部丢失而setenv.bat是给用户预留的自定义脚本升级不会动它一次写好长期有效。这也是多数线上 Tomcat 团队约定俗成的做法。如果你的 Tomcat 是做成 Windows 服务启动的还需要额外注意服务方式启动的 Tomcat 默认不读控制台的代码页setenv.bat里的参数会被tomcat9.exe等服务包装器加载但日志重定向和编码行为跟命令行启动略有差异。遇到服务启动乱码时优先检查服务属性里的 JVM 选项而不是只盯 IDEA 的配置。6. 实战排错改了这么多还乱码接下来查哪里前面的方案覆盖了IDEA 读取 → Tomcat 子进程写出 → 日志框架写出 → 磁盘文件写出理论上链路全理顺了。但真实项目里总有人改完全套还乱码这时候通常不是方案错了而是漏检了某一环。我把自己的排查链路整理成固定流程照着走一遍就清楚了。6.1 一套可以直接照做的排查链路先看文件再控制台。打开logs/catalina.date.log确认文件在 UTF-8 下是否正常。正常就重点查 IDEA 读取端不正常就查 FileHandler 和 JVM 写出端。确认 IDEA 的file.encoding真的生效了。Edit Custom VM Options改完后必须重启。可以在Help → About里打开详细列表看实际装载的 VM 参数里有没有-Dfile.encodingUTF-8。别改完不重启就在那里怀疑人生。确认运行配置里的 VM options 真的传给了子进程。最直接的办法是临时在代码里打印System.out.println(System.getProperty(file.encoding))看启动时输出的值。连子进程的编码值都不确定后面全是瞎猜。确认日志框架的 charset。Spring Boot 项目查logback-spring.xml或log4j2.xml独立 Tomcat 项目查logging.properties的 Handler 编码。不要跳过这一步很多顽固乱码就是 Logback 没写 charset 导致的。最后再查系统区域设置。如果以上全对还乱码去控制面板 → 区域 → 管理 → 更改系统区域设置看看Beta: 使用 Unicode UTF-8 提供全球语言支持是否被勾选。这个选项一旦开启Windows ANSI 代码页会变成 UTF-8很多原本按 GBK 运行的应用反而开始乱码IDEA 和 Tomcat 的行为也会被影响。我不建议为了根治乱码去勾它尤其是公司电脑可能引发一连串其他软件的乱码。如果你平时也直接在 CMD 黑窗口里启动 Tomcat顺便敲一个chcp命令看看当前代码页65001 代表 UTF-8936 代表 GBK。这个值能帮你快速理解当前 Windows 控制台环境是什么编码再配合 IDEA 的控制台编码做对比很多CMD 正常但 IDEA 乱的疑案一下就破了。6.2 五个容易忽略的隐形坑坑一只改 File Encodings不改 VM 参数。这是最常见的无效操作。File Encodings 管编辑器控制台解码管 JVM 的file.encoding两码事。第三节的步骤要配套做别拆开。坑二改了 IDEA VM 参数没重启。保存 vmoptions 只是写进了文件当前运行的 IDEA 进程还是旧参数。不重启就想看效果大概率会得到没用的错误结论。坑三数据库查询结果乱码混进来。如果乱码出现在 IDEA 的 Database 工具或查询结果窗口那不是 Tomcat 日志问题是 JDBC 连接串没指定字符集。MySQL 连接串加useUnicodetruecharacterEncodingutf8SQL Server 加characterEncodingUTF-8不同驱动写法不同。别拿 Tomcat 那套方案去折腾数据库方向不对越改越乱。坑四老项目从 Tomcat 7 升级到 9/10。Tomcat 7 及更早版本的日志默认编码不是 UTF-8升级后还可能牵扯 URIEncoding、JSP 编译编码等一堆默认值变化。升级后乱码优先检查logging.properties和server.xml里的URIEncoding再回头看启动脚本。坑五把Tomcat 后台管理页上传 war 被限制 IP和乱码混为一谈。这个是 Tomcat Manager 的conf/tomcat-users.xml或 host-manager 的 IP 访问限制配置问题跟日志乱码完全无关。很多人搜索的时候把两个问题揉在一起结果改错了文件。遇到问题先分开归类别一把梭。7. 最后聊点实际项目的经验这套方案在我带过的好几个项目里反复用过最后说几点操作之外的细节。乱码问题一定不要追求某个神奇参数一步到位而是要有顺序地验证先保证 IDEA 读取端是 UTF-8再保证 Tomcat 子进程写出端是 UTF-8然后处理日志框架和磁盘文件。顺序反了你会在错误的地方反复横跳。我自己的习惯是收到乱码反馈先打开日志文件确认再打印file.encoding然后才动手改配置。百分之八十的情况在这一步就已经找到问题了剩下的才是真正需要改配置文件的时候。团队协作时建议把编码约定写进项目文档Tomcat 统一 UTF-8、日志框架显式指定 UTF-8、IDEA 全局编码设成 UTF-8。因为乱码问题和每个人的本机环境强相关不做约定就会反复出现我这儿正常你那乱的扯皮现场。最好再在持续集成环境里跑一次验证脚本统一线上和本地的编码基线省得开发环境没问题、部署到服务器就乱。最后一个小技巧排查时在代码里临时打印一行Charset.defaultCharset().name()启动后一眼看出 JVM 默认编码是 UTF-8 还是 GBK。等确认无误再删掉这行代码比盲目改十个配置文件高效得多。如果你手头有多个 Tomcat 版本在切换也可以在启动脚本里顺手把echo %JAVA_OPTS%打印出来这样每一步启动后都能确认参数是否真的带上了排查起来事半功倍。
