企业官网建设流程全解析

1. 乱码排查的整体思路：先搞清楚字节流在哪里断了

乱码这个东西，本质上就是字节流和字符集错配。你在 IDEA 控制台看到的中文变成问号、菱形方块或者黄绿色的乱码符号，往往不是某一个地方出了问题，而是链条上的好几个环节都没对上。IDEA 控制台从 Tomcat 拿到的输出流，至少经过 Tomcat 日志输出、JVM 编码、IDEA 控制台解码、字体渲染这几道关口，任何一步用的字符集不一致，结果都是乱码。

我用一个生活化的类比来解释：编码这件事就像寄快递，发件人把中文写在一张纸上，然后按 UTF-8 的规则打包成箱子；收件人拆箱的时候，如果按 GBK 的规则来解释箱子里的字节，那拆出来的根本不是原来的字。所以排查乱码，核心就是顺着整条链路，找到发件人和收件人的规则不一致的那一环。

实际操作中最容易犯的错，是只改一个地方就指望解决全部问题。我在网上看很多教程，有的说改 IDEA 的 vmoptions，有的说改 Tomcat 的 conf 里的 logging.properties，照着弄完还是不行。原因很简单——每个教程只覆盖了链条上的一环，但你的乱码可能是两三个环节叠加导致的。所以我在下面按优先级顺序，从源码到 JVM、再到 Tomcat、最后到 IDEA 控制台和字体渲染，一层一层往下拆，每一层都说明为什么改、怎么改、改了以后解决什么问题。

2. 第一层：从源码编码统一开始，IDEA File Encodings 的正确设置

先说最基础的一步，保证项目源码本身就是 UTF-8。打开 IDEA 的 Settings，找到 Editor -> File Encodings，把三个关键项全部设为 UTF-8：

• Global Encoding：全局编码
• Project Encoding：项目编码
• Properties Files 的 Default encoding：配置文件默认编码

还要记得勾选 Transparent native-to-ascii conversion。这个 Transparent 选项的作用，是让 properties 文件里的中文以 unicode 转义形式显示，避免配置文件读取时出现编码错乱。不勾选的话，properties 文件里写的中文在保存时可能被 IDEA 按系统默认编码写入，而读取时又按另一个编码去解析，两头对不上，配置里的中文就会变成乱码。

这一步我特别想强调一个细节：很多老项目之前用的是 GBK，改完 UTF-8 之后，代码里写死的中文字符串能正常显示了，但这并不影响 JVM 运行时读取 class 文件的编码行为。JVM 默认读取 class 文件用的是 UTF-8，所以源码层面统一成 UTF-8 是第一步，也是最基本的，但它只是整个链条的起点，不是终点。如果你改完 File Encodings 之后，发现控制台还是乱码，别着急，原因大概率在下面几层。

注意：IDEA 的 File Encodings 设置只影响 IDE 本身如何读取和保存文件，不会自动传递给 Tomcat 的 JVM 进程。很多人在这里有个错觉——以为 IDEA 全局都设成 UTF-8 了，JVM 跑起来当然也应该是 UTF-8。实际上这是两码事，JVM 的编码取决于启动时的系统环境和启动参数。

另外，如果你在项目里用了 Maven 或者 Gradle，建议在构建配置里也统一指定编码。Maven 的话，在 pom.xml 的 properties 里加上 project.build.sourceEncoding 为 UTF-8；Gradle 的话，在 build.gradle 里加上 tasks.withType(JavaCompile) 的 options.encoding 设为 UTF-8。这样做的目的是保证编译期生成的 class 文件里的字符串常量和源码一致，避免编译阶段就把中文弄成了乱码。

3. 第二层：JVM 启动参数，file.encoding 必须显式声明

这一层是最容易被遗漏的。很多人会觉得，IDEA 都设成 UTF-8 了，JVM 跑起来当然也应该是 UTF-8。但实际上，JVM 的 file.encoding 取决于启动时的系统环境，在中文 Windows 上默认可能就是 GBK，IDEA 的编码设置不会自动传给 Tomcat 的 JVM 进程，所以一定要显式加上 -Dfile.encoding=UTF-8 参数。

如果你是 Spring Boot 内嵌 Tomcat，直接在 IDEA 的 Run Configuration 里加 VM options 就行。打开 Run/Debug Configurations，找到你的启动类，在 VM options 一栏里填：

-Dfile.encoding=UTF-8

如果是外部安装的 Tomcat，要改的是 Tomcat 的 bin 目录下的 catalina.bat 或者 setenv.bat。在文件里加上：

set JAVA_OPTS=-Dfile.encoding=UTF-8

这里我建议优先用 setenv.bat，因为 catalina.bat 在 Tomcat 版本升级的时候可能被覆盖，而 setenv.bat 是专门留给用户自定义环境变量的，Tomcat 升级不会动它。加了这一行之后，整个 Tomcat 进程的默认文件编码就固定为 UTF-8，包括它读取 webapp 下的资源文件、输出日志文本，都会按 UTF-8 来。

还有一个细节要注意：如果你用了 log4j、logback 这类日志框架，它们的编码设置是独立于系统属性的。也就是说，即使 JVM 的 file.encoding 设成了 UTF-8，logback 输出到文件时默认用的编码也不一定是 UTF-8，得在各自的配置文件里显式指定。logback 的话，在 logback.xml 里给 encoder 加上 UTF-8 的 charset：

<encoder charset="UTF-8"> <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder>

log4j2 的话，在 log4j2.xml 的 PatternLayout 里加上 charset 属性。这一步很关键，因为很多线上排查场景中，控制台看起来正常，但落盘日志文件打开是乱码，问题就出在日志框架没指定编码，而不是控制台的问题。

4. 第三层：外部 Tomcat 的 logging.properties，JULI 日志组件的编码开关

如果你用的是外部安装的 Tomcat，那还有一个地方必须检查——Tomcat 的 conf 目录下的 logging.properties 文件。这个文件控制的是 JULI 日志组件的输出编码，JULI 是 Tomcat 自己实现的 java.util.logging 扩展，Tomcat 启动时输出的 banner 信息、生命周期日志、部署信息，全都是由 JULI 管理的。

默认情况下，很多 Tomcat 发行版里这个文件的 ConsoleHandler 编码字段是空的，或者用的系统默认编码。这意味着如果系统默认编码是 GBK，Tomcat 启动日志里的中文（比如你部署的 webapp 名字带中文）就会按 GBK 输出字节流，而你的控制台想按 UTF-8 解码，自然就乱码了。

解决办法是编辑 conf/logging.properties，找到或者新增下面这行：

java.util.logging.ConsoleHandler.encoding = UTF-8

改完以后，保存文件并重启 Tomcat，启动时输出的 banner 信息和控制台日志就能正常显示中文了。我这里要特别提醒一句：有些版本的 Tomcat 还支持通过环境变量指定 ConsoleHandler 的编码，比如在 catalina.bat 里加：

set CATALINA_OPTS=-Djava.util.logging.ConsoleHandler.encoding=UTF-8

但实测下来，直接改 logging.properties 更稳定。因为 CATALINA_OPTS 里指定的属性优先级虽然高，但如果你后来在多个地方追加了 CATALINA_OPTS，或者在 IDE 里启动了多个 Tomcat 实例，环境变量的优先级和作用范围容易混乱，直接改配置文件反而最直观、最可控。

提示：logging.properties 只控制 JULI 输出的日志。如果你在 webapp 里用了 Log4j 或 Logback，它们输出的日志不走 JULI，编码由各自框架的配置文件决定。所以如果你发现 Tomcat 启动日志正常，但应用日志乱码，不要回头改 logging.properties，要去查 logback.xml 或者 log4j2.xml。

5. 第四层：IDEA 控制台编码，VM Options、Custom Properties 和 Console Font 一个都不能少

重点来了，很多人改完前面所有地方，Tomcat 日志还是在 IDEA 控制台里乱码，这时候问题往往出在 IDEA 自己的控制台编码上。

IDEA 控制台默认使用的编码是系统默认编码。在中文 Windows 上，这个默认编码通常就是 GBK，而 Tomcat 输出的是 UTF-8 的字节流，两边对不上就直接乱码。这一层要改三个地方，很多人只改了其中一个，所以乱码依旧。

第一个地方，打开 Help -> Edit Custom VM Options，加上：

-Dfile.encoding=UTF-8

保存后重启 IDEA。这一步是让 IDEA 进程本身以 UTF-8 编码运行。

第二个地方，打开 Settings -> Editor -> General -> Console，找到 Default encoding 选项，把它设为 UTF-8。这一步是让 IDEA 控制台组件按 UTF-8 去解码接收到的字节流。

第三个地方，打开 Help -> Edit Custom Properties（如果没有这个文件，IDEA 会提示你创建），在里面加一句：

-Dconsole.encoding=UTF-8

保存后重启 IDEA。这一步是 IDEA 专门用于控制台编码的属性，它和 VM Options 里的 file.encoding 是独立的，很多人漏掉了这一步。

我实测下来，这三步是 IDEA 控制台解码的完整链路。如果你只加了 VM Options，控制台可能还是乱码；如果只改 Console 设置，也可能不生效。必须三步都做了，控制台解码这一环节才算闭合。

这里有一个值得多说两句的小知识点：Custom VM Options 和 Custom Properties 是 IDEA 的两个不同的配置文件。VM Options 影响的是 JVM 运行参数，Custom Properties 影响的是 IDEA 平台层的系统属性，两者的作用范围不同。所以你在 VM Options 里设了 file.encoding，控制台不一定会按这个来；而 console.encoding 这个属性是 IDEA 控制台组件专门读取的，不设它，控制台解码就还是走系统默认。这也是为什么很多人改了半天只改 VM Options 却始终不生效的原因。

6. 字体渲染：编码对了但显示成方框，问题出在 Console Font

还有一个小众但很关键的点——字体渲染问题。有时候控制台输出的字节流是对的，解码也正确，但显示出来却是方框或者重叠的乱码，这通常不是编码问题，而是 IDEA 默认的控制台字体不支持中文字形。

IDEA 的默认控制台字体是 JetBrains Mono，这个字体对拉丁字母和代码符号的显示效果非常好，但对中文字形的支持并不完整。如果你的日志里中文比较多，遇到某些生僻字或者特殊字符，JetBrains Mono 渲染不了，IDEA 就会回退到系统字体去渲染，这时可能出现两种结果：一是显示成方框占位符，二是两个字符重叠在一起看起来像乱码。

解决办法是 Settings -> Editor -> Font -> Console Font，把字体换成更通用的中文字体，比如微软雅黑。同时，往下拉找到 Fallback font 设置，也设置成中文字体，比如宋体或者微软雅黑。设置了 Fallback font 之后，即使主字体缺少某个字形，也能自动回退到备用字体去渲染，避免显示成方框。

我在实际配置中把 Console Font 改成微软雅黑后，控制台输出一下子正常了。之前用默认的 JetBrains Mono 时总有零星的乱码方块，我一直以为是编码问题，折腾了很久，后来才发现是字体渲染的问题。这个坑比较隐蔽，因为它的表现和编码乱码非常像，但排查思路完全不同——编码问题是字节流层面解错了，字体问题是字节流层面完全正确、只是显示不出来。

注意：字体设置不影响日志内容的实际字节流，只影响 IDEA 渲染字符时的显示效果。如果你把日志通过重定向输出到文件，然后用文本编辑器打开，看到的还是正常的中文，那就说明编码没问题，问题单纯在字体渲染。

7. 实操流程速查表：按优先级排查，五分钟定位乱码源头

把前面几层的内容梳理成一张排查清单，实际遇到乱码的时候，按顺序从上往下走，每走一步测试一下，基本能在五分钟内定位到是哪一个环节的问题。

排查顺序：

1. 确认源码文件编码为 UTF-8。Settings -> Editor -> File Encodings，Global Encoding、Project Encoding、Properties Files 全部设为 UTF-8，勾选 Transparent native-to-ascii conversion。
2. 确认 JVM 启动参数。Spring Boot 内嵌 Tomcat 在 Run Configuration 的 VM options 里加 -Dfile.encoding=UTF-8；外部 Tomcat 在 setenv.bat 里加 set JAVA_OPTS=-Dfile.encoding=UTF-8。
3. 确认日志框架编码。logback 在 encoder 里指定 charset=UTF-8，log4j2 在 PatternLayout 里指定 charset，确保落盘文件和控制台输出一致。
4. 确认 Tomcat JULI 日志编码。外部 Tomcat 编辑 conf/logging.properties，添加 java.util.logging.ConsoleHandler.encoding=UTF-8。
5. 确认 IDEA 控制台编码。Edit Custom VM Options 加 -Dfile.encoding=UTF-8；Settings -> Editor -> General -> Console 设 Default encoding 为 UTF-8；Edit Custom Properties 加 -Dconsole.encoding=UTF-8。改完重启 IDEA。
6. 确认控制台字体。Settings -> Editor -> Font -> Console Font 换成微软雅黑，Fallback font 也设为中文字体。

每一步改完之后，重启对应的服务或者 IDEA，再看控制台输出是否正常。如果改完某一步之后乱码消失了，说明问题就出在那一步；如果没消失，继续往下走。

我在实际排查中还遇到过一种特殊情况：IDEA 内部终端（Terminal）输出正常，但 Run 控制台乱码。这种情况基本就是 Run 控制台的编码配置和内部终端不一致导致的，分别设置即可。因为 Terminal 走的是独立于 Run 控制台的一套配置，两者互不影响，你在 Settings 里改了 Console 的 Default encoding，不会影响到 Terminal 的编码行为。所以遇到这种情况，检查 Run Configuration 的 VM options 和 Custom Properties 里的 console.encoding 就行。

还有一种情况是控制台输出乱码，但日志文件打开是正常的。这种情况说明控制台解码环节出了问题，重点查 IDEA 的设置，而不是 Tomcat 或者 JVM 的设置。反过来，如果日志文件本身打开就是乱码，那就是日志框架或者 JVM 的编码问题，不是控制台的问题。这两种场景的排查方向完全不同，先判断清楚再动手，能省很多时间。

8. 多实例场景：同时跑多个 Tomcat 时怎么避免编码互相干扰

最后分享一个多实例场景的实操经验。如果你在 IDEA 里同时跑多个 Tomcat 实例，不同实例的编码可能互相影响，这种场景在微服务开发中很常见——本地要同时起两三个服务，每个服务连的数据库不同，配置也不同。

最典型的问题是：A 实例配置好了 UTF-8，B 实例还是乱码。出现这个问题的原因，往往是两个实例共用了同一个 CATALINA_BASE，导致 Tomcat 的共享配置被后启动的实例覆盖掉了。Tomcat 在启动时读取 CATALINA_BASE 下的 conf 目录，如果两个实例都指向同一个目录，那后启动的实例可能把 conf/logging.properties 里的编码设置改掉，或者加载了不同的环境变量。

解决办法是给每个实例都用独立的 CATALINA_BASE。在 IDEA 的 Run Configuration 里，给每个 Tomcat 实例分别设置环境变量 CATALINA_BASE，指向各自的目录。然后在各自的 setenv.bat 里统一配置编码参数，包括 JAVA_OPTS 里的 file.encoding 和 logging.properties 里的 ConsoleHandler.encoding。

这样即使 A 实例配置好之后 B 实例又启动，两个实例的配置也是完全隔离的，不会互相覆盖。我在实际项目中遇到过很多次这种问题，一开始以为是编码配置本身有问题，后来才发现是两个实例共用了一个 CATALINA_BASE，A 启动的时候把配置改了，B 启动的时候又把配置改回去了，导致两边的行为完全不可预测。

提示：如果你用的是 Spring Boot 内嵌 Tomcat，不管起多少个实例，每个实例都是独立的 JVM 进程，不会互相干扰编码配置。这种多实例互相干扰的问题，基本只出现在外部 Tomcat 场景。

我把这套方法整理完之后，后来又推导出一个小技巧：排查乱码的时候，先别急着改配置，先把当前乱码的内容复制出来，用十六进制编辑器看一眼字节流。比如你看到控制台输出的一段中文日志，复制到十六进制编辑器里，如果发现字节流的开头是 EF BB BF，说明输出端已经是 UTF-8 了，问题大概率出在 IDEA 控制台解码；如果字节流开头没有 BOM，而且第一个中文字符的字节是类似于 D6 D0 这样的 GBK 编码，说明输出端是 GBK，重点排查 JVM 参数和 Tomcat 的编码设置。这个方法能帮你快速判断输出端的编码，避免盲目改配置试错。

我在实际使用中还发现，IDEA 的日志输出窗口有缓存机制，有时候你改了配置重启之后，控制台显示的还是旧的乱码内容，看起来就像没改一样。这种情况下先清空控制台窗口，或者在 Run 窗口右键选择 Clear All，再重新跑一次。如果还是同样的乱码，就用十六进制看字节流的方法确认输出端的编码是否真的变了。踩过几次坑之后，我的体会是：编码问题的排查绝对不能靠猜，要有明确的链路分析思路，每一步都验证过再往下走，这样才能在最短时间内定位到真正的根源。