企业官网建设流程全解析

1. 乱码问题的根源：一个简单的原理

1.1 为什么“明明都选了UTF-8”还是乱码

先说结论：乱码的本质是字节流的编码和解码不一致。你在IDEA里写的字符串是“中文”，但它在磁盘上存下来的字节序列，和Tomcat控制台按某种规则读出来的字节序列，对不上，于是屏幕上就出现了一堆类似“浣犲ソ”、“锟斤拷”的玩意儿。

编码这事，说复杂很难，说简单其实也简单。Java的String在内存里是Unicode（UTF-16）表示的，但一旦要写入文件、写入网络流、打印到控制台，就必须“编码”成某种字节序列；另一端读取时，又必须“解码”成String。任何一步用错了字符集，就会出现“错位”。最常见的就是UTF-8编码的字节流，被GBK解码，或者反过来。UTF-8里“你”这个字占3个字节，GBK解码时按2个字节一组去拼，自然就变成了别的东西。

所以解决乱码从来不是“找个地方设置成UTF-8”这么简单，而是要保证一条链路从头到尾、每个环节都使用同一种字符集。IDEA里到处都有Encoding设置项，Tomcat也有自己的编码逻辑，再加上Windows下默认的GBK环境，整个链路只要有一个环节是GBK，你就等着在控制台里看到一堆“锟斤拷”吧。

1.2 编码链路里的三张“门禁卡”

我习惯把编码问题拆成三个环节去看，每次排查乱码都先过一遍这三关：

第一关是源码文件的保存编码。就是你在IDEA右下角看到的那个编码标识，UTF-8还是GBK。它决定了你写进磁盘里的源文件到底是什么字节。IDEA默认一般是UTF-8，但如果你打开别人发来的项目，或者某些老项目的文件是从GBK环境里拷过来的，这里很可能就是GBK。

第二关是编译编码。Java源文件是UTF-8保存的，但如果javac编译的时候用了GBK或者默认字符集去读取源文件，那么类文件里的常量池字符串就已经是错的了，运行起来必然乱码。这一关在IDEA里体现为Java Compiler的-encoding参数，在Maven里体现为project.build.sourceEncoding，在Gradle里则是compileOptions.encoding。

第三关是运行环境的输出编码。也就是程序跑起来以后，System.out打印的内容在控制台上用什么字符集显示。Tomcat控制台乱码，绝大多数问题都出在这一关。这一关也是最容易被忽略的，因为前面文件都是UTF-8，代码也没毛病，但控制台就是乱码。

搞清楚了这三关，后面所有配置就不再是“背设置项”，而是顺着链路一个个去核对的事。

2. IDEA工程编码统一：不要只改一个地方

2.1 工程文件编码的“总开关”

很多人以为在IDEA里改一个“Encoding”选项就万事大吉，其实IDEA里的编码设置散落在好几个地方，漏一个都可能让前面的努力白费。

最基础的一个，是File -> Settings -> Editor -> File Encodings。打开后你会看到三行：Global Encoding、Project Encoding、Properties Files。我的习惯是全部统一成UTF-8，一行都不留。特别是Properties Files那一项，要顺手把底部的“Create UTF-8 files”选上，否则IDEA新建的properties文件默认是ISO-8859-1，里面写中文直接会变成\uXXXX转义。

这个设置操作起来很简单，但背后有个细节容易被忽略：Project Encoding只影响“当前这个工程”的默认编码。如果你同时开好几个工程，每个工程都要检查一遍，IDEA不会因为你在A工程改了UTF-8就自动帮B工程也改。我曾经就因为同时打开两个Spring Boot项目，一个正常一个乱码，排查了半小时才发现是另一个项目的Project Encoding还挂在GBK上。

另外，IDEA从某个版本开始，会在右下角状态栏显示当前文件的编码。如果你打开的文件是UTF-8保存的，但状态栏显示的是GBK，那说明这个文件的编码被IDEA猜错了，点进去手动改成UTF-8并选择“Reload”即可。但注意，这里只是“猜测”和“显示”，它并不改变文件在磁盘上的真实字节。

2.2 Java编译参数里的“隐形杀手”

工程文件编码统一了，还有一道藏在“Build”菜单里的坑。依次打开File -> Settings -> Build, Execution, Deployment -> Compiler -> Java Compiler，右侧可以设置Additional command line parameters。第一次看到这个输入框的人多半会懵，但在这里加一行-encoding utf-8，才能保证javac在编译时用UTF-8去读取源码。

为什么要单独设这个参数？很简单，官方Java编译器在读取源码文件时，如果命令行没显式指定编码，它就去吃系统区域的默认字符集。在Windows中文环境下，这个默认值多半是GBK。于是就会出现一种极度迷惑的情况：源码文件明明是UTF-8，IDEA里看代码也完全没有问题，但编译出来的class文件里字符串已经被错误地解码重新编码，运行起来直接乱码。更坑的是，这种错误在编译阶段不会报错，它在运行时才以乱码的形式暴露出来。

如果说自己用IDEA开发，还能记得去加这个参数，那用Maven或者Gradle构建的项目就更危险了。Maven的Java编译插件默认也会依赖系统字符集，所以跨平台的项目一旦换到Windows上构建，源码是UTF-8，编译结果就可能是乱码。解决办法是在pom.xml里加上：

<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties>

Gradle的话，在build.gradle里加：

tasks.withType(JavaCompile) { options.encoding = "UTF-8" }

这属于“防御性写法”，就算你本机系统是英文版、默认是UTF-8，加了也不会有副作用；但不加，换个环境就可能崩溃。团队里只要有一个Windows用户，这里就该统一。

2.3 新建文件的“出生设置”

还有一个容易踩的坑，是IDEA新建文件时根本不会问你要什么编码，直接继承Project Encoding。如果项目是从其他机器拷过来的，Project Encoding被改成了GBK，那IDEA新建的所有文件都是GBK。哪怕你回头在File Encodings里把Project Encoding改成UTF-8，旧文件的物理编码也不会自动变，IDEA只会按当前设置去“显示”它们，有时候会出现“你看着没问题，实际上磁盘文件已经悄悄变成混合编码”的烂摊子。

所以我会建议，拿到任何外部导入的项目，第一件事不是跑起来，而是统一编码配置。顺序是：先备份，再改全工程的编码设置，然后用IDEA的File -> File Properties -> Convert Encoding把关键源码文件从GBK转换成UTF-8。注意转换之后，最好检查一下Git的Diff，确认没有大面积的文件被整体替换成“乱码修复”后的无意义变更，再提交。

这一步可以用一个笨办法验证是否成功：用任何十六进制编辑器打开源码文件，找一段中文字符串，看它在磁盘上的字节是3字节一组的UTF-8格式，还是2字节一组的GBK格式。如果你用Windows自带的记事本另存为UTF-8，其实就是在做这种事，只不过记事本会额外写入BOM头，IDEA遇到带BOM的UTF-8文件有时候会多出一个不可见字符，所以要尽量避免用记事本。

3. Tomcat控制台乱码的专项解决

3.1 先分清“谁在乱码”

Tomcat控制台乱码，我相信是Java Web开发者遇到最多的编码问题之一。但“控制台乱码”这个词其实指代了两种不同的现象，排查方向完全不同。

第一种是Tomcat自身的启动日志乱码，比如你启动Tomcat时，那些INFO、WARNING级别的日志以及启动时间、初始化信息在控制台上显示成乱码。第二种是你自己的业务代码里System.out打印的内容在控制台上乱码，或者Servlet返回给浏览器的响应乱码。这两种虽然都表现为“乱码”，但一个走的是java.util.logging（Tomcat自己用的日志体系），一个走的是标准输出流System.out，对应的配置完全是两码事。

很多教程一上来就让你改conf/logging.properties，说把java.util.logging.ConsoleHandler.encoding从UTF-8改成GBK。这个方法对第一种情况有一定帮助，但对第二种情况完全无效。我在很多项目里见过同事照着网上的教程改了logging.properties，结果业务代码打印的中文照样乱码，于是陷入“教程都是骗人的”的误区。

而且要命的是IDEA内嵌的Tomcat集成，以及外部Tomcat在命令行下启动，最终的输出流都会绕到控制台窗口，这个控制台的字符集由Windows的cmd（或IDEA的Console）决定。Windows中文版默认的代码页是936，也就是GBK。你的JVM输出是UTF-8字节流，控制台硬按GBK解码，你不乱码谁乱码。

3.2 推荐方案：统一JVM运行编码

我最推荐的一招，是在IDEA的Run Configuration里给Tomcat加上JVM参数。具体操作是：Run -> Edit Configurations -> 选择你的Tomcat配置 -> Startup/Connection -> 找到VM options，填入：

-Dfile.encoding=UTF-8

如果你用的是外部Tomcat，在启动脚本（比如bin/catalina.bat的JAVA_OPTS）里也加上同样的参数。

为什么这一招有效？因为System.out往控制台输出时，实际会经过一个PrintStream，而这个PrintStream默认会使用file.encoding作为字符集。你启动JVM时强制指定了file.encoding=UTF-8，那么System.out.println("中文")打印出来的字节流就是UTF-8序列。接下来，只要你控制台的解码方式也统一成UTF-8，问题就彻底解决了。

这里有一个最容易踩的坑：IDEA集成的Tomcat跑起来不走catalina.bat里配置的JAVA_OPTS，甚至不走它自己那个Run Configuration里的VM options，因为IDEA集成Tomcat有自己的启动逻辑。所以光改catalina.bat有时候没用，还要在IDEA的Run Configuration里同步设置。反过来，你自己命令行启动Tomcat，Run Configuration又不起作用，必须在启动脚本里改。两个入口都要知道，不能只记一个。

有一个小诀窍可以帮助快速验证这个参数是否生效：在启动的日志里看一眼，或者在代码里打印System.getProperty("file.encoding")。打印结果是UTF-8，说明参数吃进去了；还是GBK，说明你改的地方根本没被JVM读到。

3.3 备选方案：区分Tomcat自身日志与控制台

如果你的问题仅限于“Tomcat启动日志带中文显示成乱码”，而且你不想用上面的JVM参数方案，那可以改conf/logging.properties。找到下面这行：

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

把它改成GBK，或者某些版本里直接注释掉这行，Tomcat会回退到系统默认字符集（在中文Windows下就是GBK），控制台显示中文日志就正常了。这种做法在早期用Eclipse + Tomcat的时代非常流行，因为那时候Eclipse控制台默认按系统编码展示。

但我后来在实际项目中，这套做法已经不能通吃了。原因很简单：如果你在IDEA的Console里跑Tomcat，IDEA的Console默认字符集是可以自己在Settings -> Editor -> General -> Console里改的，默认也是UTF-8。这时候如果你把logging.properties改成GBK，IDEA这边反而会乱码。所以这套方案只适合“命令行cmd窗口里跑Tomcat”这种场景，而且还要先确认cmd窗口的代码页。

说白了，logging.properties只是“读取Tomcat日志文件并输出到控制台”这一层解码规则。它控制不了你业务代码里的System.out，也控制不了Windows控制台本身的字体和代码页。适用范围比很多人以为的要窄。

3.4 终极兜底方案：让Windows控制台回到UTF-8

如果你已经改了-Dfile.encoding=UTF-8，业务代码的println也正常了，但Tomcat自身的启动日志还是乱码，而且你不想动logging.properties里的编码。这种情况说明：Tomcat启动日志走的是java.util.logging，而JVM参数里的file.encoding只影响了System.out，两者不一定是同一套编码。

这时最干净的做法是让所有参与输出的角色都统一走UTF-8：首先，IDEA的Console设置成UTF-8，然后把Tomcat的logging.properties里的ConsoleHandler.encoding也改成UTF-8，同时保持-Dfile.encoding=UTF-8。在纯IDEA环境下，这三件事可以一键全统一，之后无论启动日志还是业务println，都不会乱码。这也是我在日常开发环境里最推荐的方式。

如果是在Windows自带的cmd窗口下运行，那还需要执行chcp 65001把代码页切换到UTF-8。但cmd对UTF-8的支持比较弱，字体选择不当时中文可能显示成方块，所以我个人建议在Windows下开发还是直接用IDEA的Console窗口，别跑出去用cmd，省心得多。另外提醒一句，改完这些配置后，Tomcat要完全重启，IDEA最好也重启一次，因为有些字符集是JVM启动时缓存的，热重启Hot Reload覆盖不到。

4. 排查流程与自检清单

4.1 一页纸排查流程图

乱码问题最怕的不是不懂原理，而是排查思路混乱。下面这套流程是我自己一直在用的，照着走，绝大多数编码问题10分钟内能定位。

第一步，先看源码文件本身。在IDEA里打开一个含中文的源码文件，看右下角编码标识是不是UTF-8；如果不是，先转换成UTF-8。这里有个重要提醒，转换编码时有“Reload”和“Convert”两个选项。Reload表示“按另一种编码读取当前文件”，不会改磁盘字节；Convert表示“把现有内容转换后重新保存”，会改写磁盘字节。我们一般需要的是Convert。

第二步，确认编译环节编码。如果走Maven或Gradle，看pom或build.gradle里的sourceEncoding配置；如果直接全靠IDEA编译，检查Java Compiler的Additional command line parameters里有没有-encoding utf-8。

第三步，看运行环境输出编码。检查Run Configuration里的VM options有没有-Dfile.encoding=UTF-8，外部Tomcat看启动脚本里的JAVA_OPTS；IDEA Console自身的设置有没有选UTF-8；如果还在cmd窗口跑，再补一个chcp 65001。

第四步，检查日志体系编码。如果以上都对了还是乱码，再去查Tomcat的conf/logging.properties里ConsoleHandler的encoding设置是否与你期望的输出编码一致。切记先走前三步，再动这个文件，否则容易把问题引到错误方向。

4.2 乱码问题速查表

4.3 容易被误判的“隐身乱码”

有些乱码问题表面看是Tomcat控制台，实际根源却在前端或浏览器。比如Servlet或Controller返回的JSON中文乱码，很多人狂调Tomcat编码，其实问题出在HTTP响应头里没有指定Content-Type的charset=utf-8。Tomcat 8之后HTTP请求和响应的默认编码已经从ISO-8859-1改成了UTF-8，但如果你的代码里用了老式的response.setCharacterEncoding之后又乱覆盖，或者没有设置，浏览器拿到字节流后按别的编码解析，照样乱。

碰到这类情况，我会直接在请求链路里抓包，看HTTP响应头里的Content-Type。如果charset没出现，那就是响应编码没设置好；如果出现了charset=utf-8还乱，那才回头查应用服务端到数据库之间的编码。这个经验帮我省下过很多无谓的时间，现在分享给你。

还有一种“隐身乱码”是文件编码本身没乱，但在某次编码转换后插入了BOM头。BOM是UTF-8的额外标识字节，在文件头多出EF BB BF三个字节，Java读取的时候如果没走UTF-8的Reader，这三个字节就会被打成乱码或者导致读取第一个字符串时出现空行。IDEA的右下角编码转换功能有时候会“好心”帮你加上BOM，但普遍不推荐带BOM的UTF-8文件在Java项目里混用，最好用控制台命令或者IDEA的转换选项确保文件是无BOM的UTF-8。

5. 其他值得注意的编码细节

5.1 缓存导致的“假乱码”

IDEA这个IDE什么都好，就是它的缓存机制偶尔会坑你一把。有时候你改了编码设置、改了代码、重新编译，控制台还是老样子乱码。这时候不要怀疑自己的配置哪里没对，先试试File -> Invalidate Caches / Restart。IDEA会清掉一堆编译缓存和索引，重新构建项目。我遇到过好几次“配置全对但就是乱码”的情况，一清缓存就好了。

原因其实不难推测：IDEA的编译器在某些情况下会复用旧的.class文件，而这些旧文件是用错误的编码编译出来的。虽然你改了源文件，但因为增量编译的判断逻辑没触发，它压根没重新编译那个类。清缓存相当于强制全量重建，问题自然消失。

5.2 换行符与编码无关但经常“一起来捣乱”

编码问题和行尾符问题是两个独立问题，但它们经常在同一批文件里出现，原因是它们都根源于“跨平台协作”。Windows用CRLF作为行尾，Linux/macOS用LF，IDEA右下角的LF标识旁边就是那个小下拉框。如果在文件里看到^M符号，就是行尾符不统一了。

在设置File -> Settings -> Editor -> Code Style里可以把Line separator统一成Unix and macOS (\n)，这样就算在Windows上写代码，提交到Git仓库后也不会出现文件整体变更的假Diff。虽然不直接解决乱码，但很多“改了编码提交后整个文件都红了”的问题，其实都是行尾符搞的鬼，容易被误判成编码转换出了问题。

5.3 数据库连接URL里的编码参数

如果你在项目里接MySQL，别忘了连接URL里的这几项：

jdbc:mysql://localhost:3306/dbname?useUnicode=true&characterEncoding=UTF-8

useUnicode和characterEncoding这两个参数，很多老项目里是缺失的。一旦数据库表是UTF-8、代码是从数据库读出来再打印到控制台，链路就多了一环，如果连接层没指定字符集，驱动可能用系统默认字符集去解码，中文照样乱。这个问题在Tomcat控制台里也经常被错误归结为“输出乱码”，因为前端接口返回的JSON永远是正常的，唯独控制台日志里打印数据库内容的时候是乱的。

我遇到过的真实情况是：日志里中文乱码，但网页通过接口返回的中文正常。当时第一反应是输出流编码问题，排查半天无解，后来才发现是数据库连接URL没加characterEncoding=UTF-8。所以排查乱码时，一定要把数据来源也纳入链路审计，不能只盯着IO输出。

5.4 代码里直接用字符集常量的“硬编码陷阱”

有一种乱码是“时好时坏的乱码”，偶发，重启后可能就好了，过一阵又出现。这种问题多半不是环境配置，而是代码里硬编码了字符集，比如：

new String(bytes, "GBK");

或者某个第三方库在内部偷偷用默认字符集做了一次转换。这种问题最难查，因为你的IDEA环境、配置、控制台统统没问题，但程序在某个分支里多此一举做了编码转换。排查手段是全局搜索Charset.defaultCharset()、new String、getBytes这类关键字，找到可疑的转换点，再结合日志上下文定位。我在这里踩过好几次坑，所以特别提一句：配置统一了，代码层面的“乱转”才是更隐蔽的敌人。

6. 我的个人习惯与收尾建议

关于IDEA的编码统一和Tomcat控制台乱码，讨论再多都不如养成一套固定习惯。我自己在搭建Java Web开发环境时，习惯顺序是：

先确认系统的区域设置对开发无干扰（Windows中文版天然默认GBK，这是乱码的天然温床），然后在IDEA里一次性把File Encodings全部改成UTF-8，同时把Java Compiler的参数、Maven或Gradle的sourceEncoding全部显式写好。最后在Run Configuration里启动Tomcat前，检查一遍VM options里的-Dfile.encoding=UTF-8。这套动作做完，我基本没有在编码问题上浪费过太多时间。

踩过几次坑之后，我还养成了一个“一旦怀疑乱码就随手抓证据”的习惯：用file命令或者编辑器查看文件实际字节编码，用日志框架输出当前JVM的defaultCharset，用chcp查看Windows当前代码页。把三份证据摆在一起，谁跟谁不一致一目了然，比瞎猜配置强得多。

编码问题说复杂很复杂，说简单也简单，其实就是一句话：让整条链路上的每个角色都说同一种语言。统一成UTF-8，是现代开发环境里的最优解。网上各种教程说得天花乱坠，但真正常见的乱码，九成以上都是某一处悄悄用回了GBK或者系统默认值。你能控制住每一处细节，乱码就永远不会找上你。