Eclipse 中文乱码这个问题基本每个用 Eclipse 做 Java 开发的都撞上过。明明代码逻辑没问题一跑起来控制台输出一堆问号或者看不懂的符号要么打开别人的项目全是乱码那个心情真是没办法形容。我自己在项目里也反反复复试过好几种解法这篇文章就把我这些年踩过的坑和验证过有用的方法整理出来从现象到原理再到具体操作一步步说清楚希望能让你一次搞定不用再来回折腾。1. 乱码的根源三种常见编码场景先分清Eclipse 里的中文乱码绝大多数情况不是 Eclipse 坏了而是“文件的真实编码”和“Eclipse 读取文件时使用的编码”对不上。换句话说文件里存的是 UTF-8 的字节但 Eclipse 却用 GBK 去解码那出来的内容自然就乱了。要先解决问题得先搞清楚你遇到的是哪一种场景因为不同场景的解决入口完全不同。1.1 场景一打开 Java 文件或属性文件时中文变成乱码这种最常见打开别人的项目或者从 Git 上拉下来的代码里面的中文注释、中文字符串变成了乱码。原因基本是文件的真实编码是 UTF-8但 Eclipse 工作区默认编码是 GBK在国内 Windows 上很常见或者反过来文件是 GBK 的工作区被设成了 UTF-8。1.2 场景二运行程序后控制台输出的中文是乱码这种一般代码文件看起来是正常的但一运行 System.out.println(中文)控制台里显示出来的就是乱码。这种情况通常是控制台的输出编码和程序的输出编码不一致导致的。比如程序以 UTF-8 输出控制台却按 GBK 解码显示或者反过来。1.3 场景三JSP/HTML 页面在浏览器里中文乱码这种属于网页层面的编码问题但源头往往也在 Eclipse 的文件编码设置上。JSP 文件头部声明的 pageEncoding、HTML 文件里的 meta charset和文件实际的保存编码不一致浏览器就会按错误的编码去解析。1.4 场景四properties 配置文件中中文乱码properties 文件比较特殊它默认按 ISO-8859-1 编码解析这是 Java 规范里定的。所以如果你的 properties 文件里有中文并且直接用 Eclipse 默认方式打开除非做了特殊设置否则几乎必然乱码。提示定位问题前先判断“哪个环境读哪个文件”的编码表不匹配比盲目改设置靠谱得多。改错了编码轻则乱码依旧重则把原本正常的文件也弄乱。2. 全局工作区编码一次性解决大部分 Java 文件乱码遇到打开文件是乱码的情况我一般先改工作区默认编码。这是 Eclipse 里最基础、也是影响范围最广的一项设置。2.1 操作步骤5 分钟修改 Workspace 编码打开 Eclipse点击顶部菜单栏的 Window。在下拉菜单里选择 Preferences。在弹出的窗口左侧导航树里依次展开 General然后点击 Workspace。在右侧找到 Text file encoding 区域默认选中的一般是 Other并且默认编码是 GBK国内 Windows 环境或者 UTF-8Mac/Linux 环境。选中 Other 单选框从下拉列表里选择 UTF-8。点击 Apply and Close 保存。2.2 为什么推荐用 UTF-8 而不是 GBKUTF-8 是目前跨平台、跨工具兼容性最好的编码。Linux 服务器上默认就是 UTF-8Git 仓库也普遍按 UTF-8 存储数据库连接串大多也推荐 UTF-8。如果 Eclipse 项目最终要部署到 Linux 服务器上代码文件是 GBK而服务器环境变量、日志系统是 UTF-8那乱码问题会从开发环境一路蔓延到测试、生产环境到时候排查起来会更头疼。2.3 改完还是乱码怎么办修改 Workspace 编码只对“以后打开的文件”生效而且它影响的是 Eclipse 对“无 BOM 且未声明自身编码”的文件的猜测策略。如果某个文件已经因为编码不匹配被读取过Eclipse 可能已经记住了这个文件的编码状态即使你改了全局设置它打开时仍然会沿用旧的编码。这种情况下需要手动指定单个文件的编码或者直接把文件内容重新转换一次。具体操作见下一节。3. 单文件编码修改针对已被错误读取的文件有时候改了全局编码但个别文件打开还是乱码不要慌这是 Eclipse 的一个“记忆”机制在起作用。Eclipse 会为每个文件保存一个编码属性优先于全局设置生效。3.1 手动修改单个文件编码在 Project Explorer 或 Package Explorer 里找到那个乱码的文件。右键点击文件选择 Properties。在左侧选择 Resource。右侧找到 Text file encoding默认可能是 Inherited from container (GBK)或者显示的已经是其他编码。勾选 Other从下拉列表里选择 UTF-8。点击 Apply and Close。改完以后Eclipse 会立刻用新的编码重新读取文件内容。如果文件的真实编码确实是 UTF-8那乱码立刻消失。如果还是乱的说明文件的真实编码不是 UTF-8可能是 GBK你就选择 GBK 试试。3.2 通过 Convert Line Delimiters 和编码转换区分“打开方式”和“存储方式”这里有个重要的概念要理清修改文件的编码设置改变的是 Eclipse“读取文件的方式”并不会改变文件在磁盘上的“存储字节”。如果你把文件另存为其他编码才真正改变了文件的物理存储内容。具体操作在编辑器里打开那个文件。点击菜单栏的 File选择 Save As。在 Save As 对话框右下角有一个 Encoding 下拉框如果没有点开对话框右下角的齿轮图标或下拉箭头找一下。选择你希望文件保存成的编码比如 UTF-8。点击 OK。这种方式适合你想彻底把文件从 GBK 转换成 UTF-8 的场景转换后文件内容在磁盘上的字节就变了。注意Save As 转换编码前先确认编辑器里显示的内容是不是正常的。如果你在编辑器里看到的本来就是乱码直接另存为 UTF-8 并不会修复内容反而会把乱码状态固化到文件里。必须先在编辑器里用正确编码打开看到正常中文后再另存为。3.3 批量转换多个文件的编码如果项目里有几十个文件都是 GBK 编码想统一转成 UTF-8一个个右键设置太慢了。这里分享一个我常用的批量方案用 Notepad 打开项目根目录它支持目录内批量查找替换编码。菜单栏选择 搜索然后选择 在文件中查找。在 查找目标 里输入一个能匹配多数文件的通配符比如 *.java。目录填项目源码目录编码选择 GBK自动检测然后点击 查找。确认列出的文件都是你想要的然后全选右键选择 使用 UTF-8 编码保存。这个操作会把选中的文件统一转成 UTF-8 编码。如果项目文件数量特别大也可以考虑用脚本批量转换但 Notepad 胜在可视化和即时反馈不会误操作。4. 控制台中文乱码Run Configurations 与启动参数调整控制台输出乱码是另一个高频问题。代码文件看着正常一运行就乱这通常是 JVM 默认字符集和 Eclipse 控制台的显示字符集不一致导致的。4.1 控制台乱码的两种来源第一种是程序里System.out输出的中文乱码第二种是日志框架如 Log4j、Logback输出到控制台的中文乱码。这两种问题的本质相同都是 JVM 输出字符串时的编码和控制台读取字节时的编码不一致。Java 程序运行时System.out默认使用 JVM 的file.encoding属性作为输出编码。Windows 上 JDK 8 及之前的版本这个值通常是 GBKJDK 9 及之后在某些环境下可能是 UTF-8。而 Eclipse 控制台在 Windows 上默认则倾向于按系统本地编码即 GBK读取输出字节流。于是出现了各种排列组合下的乱码。4.2 通过 Run Configurations 设置 VM 参数最直接的方法是给程序启动时加上 JVM 参数明确指定文件编码在 Eclipse 里右键包含 main 方法的类。选择 Run As然后选择 Run Configurations。在左侧选中你的启动配置。切换到 Arguments 选项卡。在 VM arguments 输入框里加上一行-Dfile.encodingUTF-8如果你的程序输出还是乱码可以再配合-Dsun.jnu.encodingUTF-8这个参数影响文件名的编码某些场景下也会影响到控制台输出。点击 Apply然后 Run。提示加上 VM 参数后建议先 Run 一次再检查乱码是否消失如果依然乱码继续调整控制台的显示编码两者配合才能解决问题。4.3 修改 Eclipse 控制台显示编码Eclipse 控制台的显示编码在少数版本里没有直接在 UI 里修改的入口但大部分版本可以通过以下方式找到在控制台视图里点击右上角的小倒三角图标View Menu。选择 Console打开控制台设置面板。查看或修改 Encoding 选项部分版本显示为 Text Encoding。将其设置为 UTF-8或者根据你的程序输出编码来设置。如果找不到这个选项也可以直接修改 Eclipse 安装目录下的配置文件但那个方法更底层不推荐日常使用。有一个相对简洁的替代方案在控制台视图中右键选择 Preferences在弹出的对话框中搜索 encoding也能快速定位到相关设置。4.4 最省事的控制台乱码排查套路如果你不想记那么多参数和选项就按这个顺序排查先看代码文件本身的编码是不是 UTF-8右键文件 → Properties → Resource。再看 Run Configurations 里有没有-Dfile.encodingUTF-8没有就加上。最后看控制台设置里的编码不行就换个编码试GBK 和 UTF-8 之间切换。这三步覆盖了 95% 以上的控制台乱码问题。5. JSP/HTML/XML 页面中文乱码三处编码统一原则网页层面的乱码通常涉及的环节更多但核心就一条三处编码必须统一即文件的保存编码、页面声明编码、服务器响应编码三者必须一致。5.1 JSP 文件的编码设置JSP 文件头部通常有一段声明% page languagejava contentTypetext/html; charsetUTF-8 pageEncodingUTF-8%这里的contentType里的 charset 和pageEncoding都必须设置为 UTF-8。但这还不够还需要保证文件本身在磁盘上的保存编码也是 UTF-8。如果文件本身是 GBK 保存的页面声明却是 UTF-8那在浏览器里一样是乱码。所以设置完 JSP 声明后记得检查文件属性里的编码。5.2 HTML 文件的编码设置HTML 文件在head里一般有meta charsetUTF-8同样这里的 charset 需要和文件保存编码一致。如果 HTML 文件是 Eclipse 里新建的默认编码会继承工作区编码也就是你之前在 Workspace 设置里配置的值。所以务必把工作区默认编码设为 UTF-8然后再新建 HTML 文件这样出来的文件就是 UTF-8声明也是 UTF-8。5.3 XML 和 properties 文件乱码XML 文件通常在首行声明编码?xml version1.0 encodingUTF-8?这里声明的 encoding 要和文件保存编码一致。properties 文件比较特殊Java 规范要求 properties 文件使用 ISO-8859-1 编码但中文在这种编码下无法直接表示。所以常规做法是使用 Unicode 转义序列即\uXXXX格式或者用 Eclipse 的插件如 PropertiesEditor来直接编写中文由插件负责转码。如果你没有装插件直接用 Eclipse 默认编辑器写 properties 文件中的中文写进去的时候看着正常保存后 Eclipse 会按 ISO-8859-1 解析再打开就变成乱码。这种场景我一般会安装 PropertiesEditor 插件或者直接避免在 properties 文件里写中文改用代码里配置或者写一个 ResourceBundle 的 UTF-8 实现类。6. 数据库和文件读写乱码从源头查字符集很多项目的乱码不是发生在 Eclipse 界面里而是数据从 Java 程序写入数据库后再从数据库里查出来变成乱码。这种问题严格说不是 Eclipse 的问题但因为是开发调试期在 Eclipse 里发现的也被很多人当成“Eclipse 乱码”来搜索。6.1 JDBC 连接串里指定字符集在使用 MySQL 时JDBC 连接串上一般要加上characterEncodingutf8比如jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8这里必须注意的是MySQL 的 utf8 实际是 utf8mb3不完全支持四字节的 emoji 字符。如果业务场景涉及 emoji推荐换成characterEncodingutf8mb4。MySQL 驱动 8.0 版本对 utf8mb4 支持更好。6.2 数据库表本身要设置 utf8mb4数据库连接的编码只决定了 Java 程序和 MySQL 之间的传输编码。如果表本身的字符集是 latin1 或 gbk那最终存储的还是错误编码。建表时推荐显式指定CREATE TABLE user ( id int(11) NOT NULL AUTO_INCREMENT, name varchar(50) DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci;如果表已经建好了可以用 ALTER 语句修改字符集但要小心历史数据修改之前先备份。6.3 文件读写乱码Java 里读写文本文件时如果不显式指定编码会使用 JVM 的file.encoding默认值。这在跨平台部署时很容易出问题。稳妥的做法是读写文件都显式指定 UTF-8BufferedReader reader new BufferedReader(new InputStreamReader(new FileInputStream(file.txt), UTF-8)); BufferedWriter writer new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file.txt), UTF-8));不要使用 FileReader 和 FileWriter因为它们没有指定编码的构造方法在 Windows 上默认按 GBK 处理写出来的文件在其他平台上很可能乱码。7. 典型排查思路从现象到方案的对照速查有时候乱码问题不是单一原因可能是多个因素叠加。我整理了一个排查速查表每次遇到乱码先对着表格判断一下比盲目改设置快很多。乱码现象最常见原因解决入口打开 .java 文件中文注释乱码文件保存编码与工作区编码不一致右键文件 → Properties → Resource → 修改 Text file encoding控制台 System.out 中文乱码JVM 输出编码与控制台显示编码不一致Run Configurations → VM arguments 加 -Dfile.encodingUTF-8JSP 页面浏览器显示乱码pageEncoding、contentType、文件保存编码不一致统一三处编码为 UTF-8properties 文件中文乱码Java 规范默认 ISO-8859-1 解析安装 PropertiesEditor 插件或改用 Unicode 转义数据库存储中文乱码JDBC 连接串或数据表字符集不对连接串加 characterEncoding表字符集改 utf8mb4这个表是我在实际处理问题中反复验证过的。每次遇到乱码我都会先问一句到底是“哪个程序、用什么编码、读哪个文件、输出到哪里”把这个链条理清楚基本就定位到问题区间了。8. 用编码转换工具和外部编辑器辅助修复Eclipse 自带的编码修改功能应对单个文件没问题但批量转换、或者遇到文件内容已经被错误编码污染的情况就要借助外部工具了。8.1 Notepad 转换编码Notepad 是我最常用来处理编码问题的工具。打开乱码文件。菜单栏选择 编码如果当前编码是“以 UTF-8 编码”但显示乱码先选择“以 ANSI 编码”或“以 GB2312 编码”看是否能正常显示。当切换编码后内容显示正常说明文件的真实编码是刚才选的那个。确认内容显示正常后再选择 编码 → 转为 UTF-8 编码。这个“先切换显示编码、再另存为目标编码”的思路非常重要。很多人一上来直接“转为 UTF-8”但没确认内容是否正常结果转换完乱码反而变本加厉。8.2 批量修改文件编码的命令行方案Linux 或 macOS 环境下可以用 iconv 命令批量转换find ./src -name *.java -exec iconv -f GBK -t UTF-8 {} -o {}.tmp \;Windows 上如果没有 iconv可以用 Git Bash 运行同样的命令或者用 Python 脚本import os import codecs src_dir ./src for root, dirs, files in os.walk(src_dir): for f in files: if f.endswith(.java): path os.path.join(root, f) try: content codecs.open(path, r, gbk).read() codecs.open(path, w, utf-8).write(content) print(fconverted: {path}) except UnicodeDecodeError: print(fskip (not gbk): {path})这里有个细节要注意如果文件里同时包含 GBK 和 UTF-8 两种编码的字符比如历史遗留的拼接转换时可能会报 UnicodeDecodeError。遇到这种情况可以用errorsignore或errorsreplace参数跳过异常但转换结果需要人工复核不能盲目相信脚本输出。8.3 使用 Eclipse 插件辅助管理编码市场上有一些 Eclipse 插件可以帮助统一管理编码比如 ResourceBundle Editor 可以编辑 properties 文件而不需要手动转码。还有 Bytecode Outline 之类的工具可以在底层查看 class 文件的编码信息。但这种插件治标不治本最终还是要靠团队统一编码规范。9. 从源头预防项目构建时就把编码固化处理乱码最理想的方式是不让它发生。在团队项目里如果把编码规范固化在项目构建配置里乱码问题几乎可以被消灭在萌芽状态。9.1 Maven 项目统一编码在 pom.xml 里显式设置项目编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties同时在 maven-compiler-plugin 里也指定编码plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.11.0/version configuration encodingUTF-8/encoding source1.8/source target1.8/target /configuration /plugin这样配置后Maven 编译时会按 UTF-8 读取源码即使开发者的 Eclipse 工作区没设置好Maven 构建时也能以正确编码编译。9.2 Git 配置统一换行符和编码Git 在 Windows 上默认会自动转换换行符这本身不改变文件编码但会影响某些工具的判断。在 .gitattributes 文件里可以统一声明文本文件的编码类型*.java text eollf *.properties text eollf *.xml text eollf换行符统一为 LF 后跨平台拉取代码时不容易因为换行符差异导致文件内容异常。后续配合 IDE 的编码设置整个项目在团队协作中的编码一致性会高很多。9.3 IDE 编码模板设置在 Eclipse 里Window → Preferences → General → Content Types 下可以针对不同类型的文件单独设置默认编码选中 Text。在下方的 Default encoding 输入框里填 UTF-8。点击 Update。这样针对 java、properties、xml 等文件类型Eclipse 会优先按 UTF-8 处理就算工作区编码被误改这些文件也能正确显示。注意以上这些设置最好在项目初始化时完成而不是等代码写了一半、乱码已经出现再补救。项目初期把编码规范定清楚后面维护成本会低很多。根据我个人的维护经验团队项目里统一编码的收益远大于迁就个别工具默认设置的代价。10. 常见问题与避坑经验实操中踩过的坑整理几个我实际处理编码问题时的教训有些折腾了很久才发现是这么回事。10.1 改完编码后文件反而全乱了这是最常见的返工事故。原因是文件原本是 GBK 编码Eclipse 按 GBK 打开显示正常高高兴兴地把工作区编码改成 UTF-8结果 Eclipse 立即按 UTF-8 重新解码文件中文自然全乱。这还不是最糟的如果你在乱码状态下直接保存文件内容就被覆盖成“用 UTF-8 解码出来的乱码字符序列”原始内容再难恢复。避坑做法改编码之前先确认当前编辑器里显示的内容是正常的。如果正常想转编码请用“另存为”的方式转换而不是直接改工作区编码。10.2 控制台编码改了没反应有些版本的控制台编码设置是只读的或者设置入口不在 View Menu 里。这时候先检查 Run Configurations 里的 VM 参数加上-Dfile.encodingUTF-8再试。如果还不行直接把控制台窗口关闭再重新打开一次有时候是旧输出流缓存的残留。10.3 Eclipse 版本对编码设置的支持有差异不同版本的 Eclipse 在编码设置的位置上略有差异。Eclipse 2020-06 之前和之后的版本Preferences 窗口的搜索功能都支持直接搜索 “encoding”建议直接搜索比手动一层层点进去快得多。10.4 文件编码检测工具万一不知道文件到底是什么编码可以用 Notepad 打开文件右下角会显示当前文件的编码。如果不准切换几种常见编码观察显示效果。也可以用命令行工具 filefile -i MyClass.java这个命令会输出文件的 MIME 类型和字符集比如charsetutf-8或charsetiso-8859-1对于批量检测文件编码很有帮助。10.5 从网页复制代码导致乱码从网页上直接复制代码粘贴到 Eclipse 里有时候粘贴进来的中文是乱码。这种问题跟 Eclipse 编码设置无关而是浏览器网页本身的编码与剪贴板转换的问题。建议粘贴后立即检查代码里的注释和字符串如果乱码先粘贴到 Notepad 里强制转成 UTF-8再复制进 Eclipse。10.6 项目编码和服务器编码不一致本地 Eclipse 设成 UTF-8代码部署到 Linux 服务器上如果服务器上 Tomcat 等容器的 URIEncoding 没设置接收请求参数时也可能出现乱码。Tomcat 可以在 server.xml 里配置Connector port8080 protocolHTTP/1.1 URIEncodingUTF-8/这个配置项属于服务器层面但很多人是在 Eclipse 里调试时遇到的以为是自己代码的问题排查了半天才发现是容器的编码没设置。11. 最后的经验体会中文乱码问题看着简单但实际处理起来涉及的环节非常多。文件编码、工作区编码、控制台编码、JVM 编码、容器编码、数据库编码任何一个环节不一致都会导致乱码。最有效的排查思路永远是先搞清楚数据从哪来、流向哪去、中间经过了哪些转换环节把整个链路梳理清楚后再一个个检查各环节的编码配置。我个人在项目里的做法是新项目建立的第一步就把 Eclipse 工作区编码、Maven 编码、Git 换行符全部统一为 UTF-8并且在团队文档里写明编码规范。后续团队成员拉取代码、编译、部署都不会因为编码问题浪费额外时间。如果你现在正好被 Eclipse 中文乱码困扰建议先按照文章里的速查表定位问题场景再针对性操作。大多数情况下全局工作区改成 UTF-8 加 Run Configurations 加 VM 参数这两步就能覆盖绝大部分问题。如果还不行就用 Notepad 检查文件真实编码再配合项目级编码设置基本没有解决不了的乱码。最后再提醒一句乱码问题处理过程中一定要先确认编辑器里显示正常再进行另存为转换否则操作不当还可能把原始文件内容弄丢得不偿失。
Eclipse中文乱码根源与彻底解决方法
Eclipse 中文乱码这个问题基本每个用 Eclipse 做 Java 开发的都撞上过。明明代码逻辑没问题一跑起来控制台输出一堆问号或者看不懂的符号要么打开别人的项目全是乱码那个心情真是没办法形容。我自己在项目里也反反复复试过好几种解法这篇文章就把我这些年踩过的坑和验证过有用的方法整理出来从现象到原理再到具体操作一步步说清楚希望能让你一次搞定不用再来回折腾。1. 乱码的根源三种常见编码场景先分清Eclipse 里的中文乱码绝大多数情况不是 Eclipse 坏了而是“文件的真实编码”和“Eclipse 读取文件时使用的编码”对不上。换句话说文件里存的是 UTF-8 的字节但 Eclipse 却用 GBK 去解码那出来的内容自然就乱了。要先解决问题得先搞清楚你遇到的是哪一种场景因为不同场景的解决入口完全不同。1.1 场景一打开 Java 文件或属性文件时中文变成乱码这种最常见打开别人的项目或者从 Git 上拉下来的代码里面的中文注释、中文字符串变成了乱码。原因基本是文件的真实编码是 UTF-8但 Eclipse 工作区默认编码是 GBK在国内 Windows 上很常见或者反过来文件是 GBK 的工作区被设成了 UTF-8。1.2 场景二运行程序后控制台输出的中文是乱码这种一般代码文件看起来是正常的但一运行 System.out.println(中文)控制台里显示出来的就是乱码。这种情况通常是控制台的输出编码和程序的输出编码不一致导致的。比如程序以 UTF-8 输出控制台却按 GBK 解码显示或者反过来。1.3 场景三JSP/HTML 页面在浏览器里中文乱码这种属于网页层面的编码问题但源头往往也在 Eclipse 的文件编码设置上。JSP 文件头部声明的 pageEncoding、HTML 文件里的 meta charset和文件实际的保存编码不一致浏览器就会按错误的编码去解析。1.4 场景四properties 配置文件中中文乱码properties 文件比较特殊它默认按 ISO-8859-1 编码解析这是 Java 规范里定的。所以如果你的 properties 文件里有中文并且直接用 Eclipse 默认方式打开除非做了特殊设置否则几乎必然乱码。提示定位问题前先判断“哪个环境读哪个文件”的编码表不匹配比盲目改设置靠谱得多。改错了编码轻则乱码依旧重则把原本正常的文件也弄乱。2. 全局工作区编码一次性解决大部分 Java 文件乱码遇到打开文件是乱码的情况我一般先改工作区默认编码。这是 Eclipse 里最基础、也是影响范围最广的一项设置。2.1 操作步骤5 分钟修改 Workspace 编码打开 Eclipse点击顶部菜单栏的 Window。在下拉菜单里选择 Preferences。在弹出的窗口左侧导航树里依次展开 General然后点击 Workspace。在右侧找到 Text file encoding 区域默认选中的一般是 Other并且默认编码是 GBK国内 Windows 环境或者 UTF-8Mac/Linux 环境。选中 Other 单选框从下拉列表里选择 UTF-8。点击 Apply and Close 保存。2.2 为什么推荐用 UTF-8 而不是 GBKUTF-8 是目前跨平台、跨工具兼容性最好的编码。Linux 服务器上默认就是 UTF-8Git 仓库也普遍按 UTF-8 存储数据库连接串大多也推荐 UTF-8。如果 Eclipse 项目最终要部署到 Linux 服务器上代码文件是 GBK而服务器环境变量、日志系统是 UTF-8那乱码问题会从开发环境一路蔓延到测试、生产环境到时候排查起来会更头疼。2.3 改完还是乱码怎么办修改 Workspace 编码只对“以后打开的文件”生效而且它影响的是 Eclipse 对“无 BOM 且未声明自身编码”的文件的猜测策略。如果某个文件已经因为编码不匹配被读取过Eclipse 可能已经记住了这个文件的编码状态即使你改了全局设置它打开时仍然会沿用旧的编码。这种情况下需要手动指定单个文件的编码或者直接把文件内容重新转换一次。具体操作见下一节。3. 单文件编码修改针对已被错误读取的文件有时候改了全局编码但个别文件打开还是乱码不要慌这是 Eclipse 的一个“记忆”机制在起作用。Eclipse 会为每个文件保存一个编码属性优先于全局设置生效。3.1 手动修改单个文件编码在 Project Explorer 或 Package Explorer 里找到那个乱码的文件。右键点击文件选择 Properties。在左侧选择 Resource。右侧找到 Text file encoding默认可能是 Inherited from container (GBK)或者显示的已经是其他编码。勾选 Other从下拉列表里选择 UTF-8。点击 Apply and Close。改完以后Eclipse 会立刻用新的编码重新读取文件内容。如果文件的真实编码确实是 UTF-8那乱码立刻消失。如果还是乱的说明文件的真实编码不是 UTF-8可能是 GBK你就选择 GBK 试试。3.2 通过 Convert Line Delimiters 和编码转换区分“打开方式”和“存储方式”这里有个重要的概念要理清修改文件的编码设置改变的是 Eclipse“读取文件的方式”并不会改变文件在磁盘上的“存储字节”。如果你把文件另存为其他编码才真正改变了文件的物理存储内容。具体操作在编辑器里打开那个文件。点击菜单栏的 File选择 Save As。在 Save As 对话框右下角有一个 Encoding 下拉框如果没有点开对话框右下角的齿轮图标或下拉箭头找一下。选择你希望文件保存成的编码比如 UTF-8。点击 OK。这种方式适合你想彻底把文件从 GBK 转换成 UTF-8 的场景转换后文件内容在磁盘上的字节就变了。注意Save As 转换编码前先确认编辑器里显示的内容是不是正常的。如果你在编辑器里看到的本来就是乱码直接另存为 UTF-8 并不会修复内容反而会把乱码状态固化到文件里。必须先在编辑器里用正确编码打开看到正常中文后再另存为。3.3 批量转换多个文件的编码如果项目里有几十个文件都是 GBK 编码想统一转成 UTF-8一个个右键设置太慢了。这里分享一个我常用的批量方案用 Notepad 打开项目根目录它支持目录内批量查找替换编码。菜单栏选择 搜索然后选择 在文件中查找。在 查找目标 里输入一个能匹配多数文件的通配符比如 *.java。目录填项目源码目录编码选择 GBK自动检测然后点击 查找。确认列出的文件都是你想要的然后全选右键选择 使用 UTF-8 编码保存。这个操作会把选中的文件统一转成 UTF-8 编码。如果项目文件数量特别大也可以考虑用脚本批量转换但 Notepad 胜在可视化和即时反馈不会误操作。4. 控制台中文乱码Run Configurations 与启动参数调整控制台输出乱码是另一个高频问题。代码文件看着正常一运行就乱这通常是 JVM 默认字符集和 Eclipse 控制台的显示字符集不一致导致的。4.1 控制台乱码的两种来源第一种是程序里System.out输出的中文乱码第二种是日志框架如 Log4j、Logback输出到控制台的中文乱码。这两种问题的本质相同都是 JVM 输出字符串时的编码和控制台读取字节时的编码不一致。Java 程序运行时System.out默认使用 JVM 的file.encoding属性作为输出编码。Windows 上 JDK 8 及之前的版本这个值通常是 GBKJDK 9 及之后在某些环境下可能是 UTF-8。而 Eclipse 控制台在 Windows 上默认则倾向于按系统本地编码即 GBK读取输出字节流。于是出现了各种排列组合下的乱码。4.2 通过 Run Configurations 设置 VM 参数最直接的方法是给程序启动时加上 JVM 参数明确指定文件编码在 Eclipse 里右键包含 main 方法的类。选择 Run As然后选择 Run Configurations。在左侧选中你的启动配置。切换到 Arguments 选项卡。在 VM arguments 输入框里加上一行-Dfile.encodingUTF-8如果你的程序输出还是乱码可以再配合-Dsun.jnu.encodingUTF-8这个参数影响文件名的编码某些场景下也会影响到控制台输出。点击 Apply然后 Run。提示加上 VM 参数后建议先 Run 一次再检查乱码是否消失如果依然乱码继续调整控制台的显示编码两者配合才能解决问题。4.3 修改 Eclipse 控制台显示编码Eclipse 控制台的显示编码在少数版本里没有直接在 UI 里修改的入口但大部分版本可以通过以下方式找到在控制台视图里点击右上角的小倒三角图标View Menu。选择 Console打开控制台设置面板。查看或修改 Encoding 选项部分版本显示为 Text Encoding。将其设置为 UTF-8或者根据你的程序输出编码来设置。如果找不到这个选项也可以直接修改 Eclipse 安装目录下的配置文件但那个方法更底层不推荐日常使用。有一个相对简洁的替代方案在控制台视图中右键选择 Preferences在弹出的对话框中搜索 encoding也能快速定位到相关设置。4.4 最省事的控制台乱码排查套路如果你不想记那么多参数和选项就按这个顺序排查先看代码文件本身的编码是不是 UTF-8右键文件 → Properties → Resource。再看 Run Configurations 里有没有-Dfile.encodingUTF-8没有就加上。最后看控制台设置里的编码不行就换个编码试GBK 和 UTF-8 之间切换。这三步覆盖了 95% 以上的控制台乱码问题。5. JSP/HTML/XML 页面中文乱码三处编码统一原则网页层面的乱码通常涉及的环节更多但核心就一条三处编码必须统一即文件的保存编码、页面声明编码、服务器响应编码三者必须一致。5.1 JSP 文件的编码设置JSP 文件头部通常有一段声明% page languagejava contentTypetext/html; charsetUTF-8 pageEncodingUTF-8%这里的contentType里的 charset 和pageEncoding都必须设置为 UTF-8。但这还不够还需要保证文件本身在磁盘上的保存编码也是 UTF-8。如果文件本身是 GBK 保存的页面声明却是 UTF-8那在浏览器里一样是乱码。所以设置完 JSP 声明后记得检查文件属性里的编码。5.2 HTML 文件的编码设置HTML 文件在head里一般有meta charsetUTF-8同样这里的 charset 需要和文件保存编码一致。如果 HTML 文件是 Eclipse 里新建的默认编码会继承工作区编码也就是你之前在 Workspace 设置里配置的值。所以务必把工作区默认编码设为 UTF-8然后再新建 HTML 文件这样出来的文件就是 UTF-8声明也是 UTF-8。5.3 XML 和 properties 文件乱码XML 文件通常在首行声明编码?xml version1.0 encodingUTF-8?这里声明的 encoding 要和文件保存编码一致。properties 文件比较特殊Java 规范要求 properties 文件使用 ISO-8859-1 编码但中文在这种编码下无法直接表示。所以常规做法是使用 Unicode 转义序列即\uXXXX格式或者用 Eclipse 的插件如 PropertiesEditor来直接编写中文由插件负责转码。如果你没有装插件直接用 Eclipse 默认编辑器写 properties 文件中的中文写进去的时候看着正常保存后 Eclipse 会按 ISO-8859-1 解析再打开就变成乱码。这种场景我一般会安装 PropertiesEditor 插件或者直接避免在 properties 文件里写中文改用代码里配置或者写一个 ResourceBundle 的 UTF-8 实现类。6. 数据库和文件读写乱码从源头查字符集很多项目的乱码不是发生在 Eclipse 界面里而是数据从 Java 程序写入数据库后再从数据库里查出来变成乱码。这种问题严格说不是 Eclipse 的问题但因为是开发调试期在 Eclipse 里发现的也被很多人当成“Eclipse 乱码”来搜索。6.1 JDBC 连接串里指定字符集在使用 MySQL 时JDBC 连接串上一般要加上characterEncodingutf8比如jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8这里必须注意的是MySQL 的 utf8 实际是 utf8mb3不完全支持四字节的 emoji 字符。如果业务场景涉及 emoji推荐换成characterEncodingutf8mb4。MySQL 驱动 8.0 版本对 utf8mb4 支持更好。6.2 数据库表本身要设置 utf8mb4数据库连接的编码只决定了 Java 程序和 MySQL 之间的传输编码。如果表本身的字符集是 latin1 或 gbk那最终存储的还是错误编码。建表时推荐显式指定CREATE TABLE user ( id int(11) NOT NULL AUTO_INCREMENT, name varchar(50) DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci;如果表已经建好了可以用 ALTER 语句修改字符集但要小心历史数据修改之前先备份。6.3 文件读写乱码Java 里读写文本文件时如果不显式指定编码会使用 JVM 的file.encoding默认值。这在跨平台部署时很容易出问题。稳妥的做法是读写文件都显式指定 UTF-8BufferedReader reader new BufferedReader(new InputStreamReader(new FileInputStream(file.txt), UTF-8)); BufferedWriter writer new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file.txt), UTF-8));不要使用 FileReader 和 FileWriter因为它们没有指定编码的构造方法在 Windows 上默认按 GBK 处理写出来的文件在其他平台上很可能乱码。7. 典型排查思路从现象到方案的对照速查有时候乱码问题不是单一原因可能是多个因素叠加。我整理了一个排查速查表每次遇到乱码先对着表格判断一下比盲目改设置快很多。乱码现象最常见原因解决入口打开 .java 文件中文注释乱码文件保存编码与工作区编码不一致右键文件 → Properties → Resource → 修改 Text file encoding控制台 System.out 中文乱码JVM 输出编码与控制台显示编码不一致Run Configurations → VM arguments 加 -Dfile.encodingUTF-8JSP 页面浏览器显示乱码pageEncoding、contentType、文件保存编码不一致统一三处编码为 UTF-8properties 文件中文乱码Java 规范默认 ISO-8859-1 解析安装 PropertiesEditor 插件或改用 Unicode 转义数据库存储中文乱码JDBC 连接串或数据表字符集不对连接串加 characterEncoding表字符集改 utf8mb4这个表是我在实际处理问题中反复验证过的。每次遇到乱码我都会先问一句到底是“哪个程序、用什么编码、读哪个文件、输出到哪里”把这个链条理清楚基本就定位到问题区间了。8. 用编码转换工具和外部编辑器辅助修复Eclipse 自带的编码修改功能应对单个文件没问题但批量转换、或者遇到文件内容已经被错误编码污染的情况就要借助外部工具了。8.1 Notepad 转换编码Notepad 是我最常用来处理编码问题的工具。打开乱码文件。菜单栏选择 编码如果当前编码是“以 UTF-8 编码”但显示乱码先选择“以 ANSI 编码”或“以 GB2312 编码”看是否能正常显示。当切换编码后内容显示正常说明文件的真实编码是刚才选的那个。确认内容显示正常后再选择 编码 → 转为 UTF-8 编码。这个“先切换显示编码、再另存为目标编码”的思路非常重要。很多人一上来直接“转为 UTF-8”但没确认内容是否正常结果转换完乱码反而变本加厉。8.2 批量修改文件编码的命令行方案Linux 或 macOS 环境下可以用 iconv 命令批量转换find ./src -name *.java -exec iconv -f GBK -t UTF-8 {} -o {}.tmp \;Windows 上如果没有 iconv可以用 Git Bash 运行同样的命令或者用 Python 脚本import os import codecs src_dir ./src for root, dirs, files in os.walk(src_dir): for f in files: if f.endswith(.java): path os.path.join(root, f) try: content codecs.open(path, r, gbk).read() codecs.open(path, w, utf-8).write(content) print(fconverted: {path}) except UnicodeDecodeError: print(fskip (not gbk): {path})这里有个细节要注意如果文件里同时包含 GBK 和 UTF-8 两种编码的字符比如历史遗留的拼接转换时可能会报 UnicodeDecodeError。遇到这种情况可以用errorsignore或errorsreplace参数跳过异常但转换结果需要人工复核不能盲目相信脚本输出。8.3 使用 Eclipse 插件辅助管理编码市场上有一些 Eclipse 插件可以帮助统一管理编码比如 ResourceBundle Editor 可以编辑 properties 文件而不需要手动转码。还有 Bytecode Outline 之类的工具可以在底层查看 class 文件的编码信息。但这种插件治标不治本最终还是要靠团队统一编码规范。9. 从源头预防项目构建时就把编码固化处理乱码最理想的方式是不让它发生。在团队项目里如果把编码规范固化在项目构建配置里乱码问题几乎可以被消灭在萌芽状态。9.1 Maven 项目统一编码在 pom.xml 里显式设置项目编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties同时在 maven-compiler-plugin 里也指定编码plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.11.0/version configuration encodingUTF-8/encoding source1.8/source target1.8/target /configuration /plugin这样配置后Maven 编译时会按 UTF-8 读取源码即使开发者的 Eclipse 工作区没设置好Maven 构建时也能以正确编码编译。9.2 Git 配置统一换行符和编码Git 在 Windows 上默认会自动转换换行符这本身不改变文件编码但会影响某些工具的判断。在 .gitattributes 文件里可以统一声明文本文件的编码类型*.java text eollf *.properties text eollf *.xml text eollf换行符统一为 LF 后跨平台拉取代码时不容易因为换行符差异导致文件内容异常。后续配合 IDE 的编码设置整个项目在团队协作中的编码一致性会高很多。9.3 IDE 编码模板设置在 Eclipse 里Window → Preferences → General → Content Types 下可以针对不同类型的文件单独设置默认编码选中 Text。在下方的 Default encoding 输入框里填 UTF-8。点击 Update。这样针对 java、properties、xml 等文件类型Eclipse 会优先按 UTF-8 处理就算工作区编码被误改这些文件也能正确显示。注意以上这些设置最好在项目初始化时完成而不是等代码写了一半、乱码已经出现再补救。项目初期把编码规范定清楚后面维护成本会低很多。根据我个人的维护经验团队项目里统一编码的收益远大于迁就个别工具默认设置的代价。10. 常见问题与避坑经验实操中踩过的坑整理几个我实际处理编码问题时的教训有些折腾了很久才发现是这么回事。10.1 改完编码后文件反而全乱了这是最常见的返工事故。原因是文件原本是 GBK 编码Eclipse 按 GBK 打开显示正常高高兴兴地把工作区编码改成 UTF-8结果 Eclipse 立即按 UTF-8 重新解码文件中文自然全乱。这还不是最糟的如果你在乱码状态下直接保存文件内容就被覆盖成“用 UTF-8 解码出来的乱码字符序列”原始内容再难恢复。避坑做法改编码之前先确认当前编辑器里显示的内容是正常的。如果正常想转编码请用“另存为”的方式转换而不是直接改工作区编码。10.2 控制台编码改了没反应有些版本的控制台编码设置是只读的或者设置入口不在 View Menu 里。这时候先检查 Run Configurations 里的 VM 参数加上-Dfile.encodingUTF-8再试。如果还不行直接把控制台窗口关闭再重新打开一次有时候是旧输出流缓存的残留。10.3 Eclipse 版本对编码设置的支持有差异不同版本的 Eclipse 在编码设置的位置上略有差异。Eclipse 2020-06 之前和之后的版本Preferences 窗口的搜索功能都支持直接搜索 “encoding”建议直接搜索比手动一层层点进去快得多。10.4 文件编码检测工具万一不知道文件到底是什么编码可以用 Notepad 打开文件右下角会显示当前文件的编码。如果不准切换几种常见编码观察显示效果。也可以用命令行工具 filefile -i MyClass.java这个命令会输出文件的 MIME 类型和字符集比如charsetutf-8或charsetiso-8859-1对于批量检测文件编码很有帮助。10.5 从网页复制代码导致乱码从网页上直接复制代码粘贴到 Eclipse 里有时候粘贴进来的中文是乱码。这种问题跟 Eclipse 编码设置无关而是浏览器网页本身的编码与剪贴板转换的问题。建议粘贴后立即检查代码里的注释和字符串如果乱码先粘贴到 Notepad 里强制转成 UTF-8再复制进 Eclipse。10.6 项目编码和服务器编码不一致本地 Eclipse 设成 UTF-8代码部署到 Linux 服务器上如果服务器上 Tomcat 等容器的 URIEncoding 没设置接收请求参数时也可能出现乱码。Tomcat 可以在 server.xml 里配置Connector port8080 protocolHTTP/1.1 URIEncodingUTF-8/这个配置项属于服务器层面但很多人是在 Eclipse 里调试时遇到的以为是自己代码的问题排查了半天才发现是容器的编码没设置。11. 最后的经验体会中文乱码问题看着简单但实际处理起来涉及的环节非常多。文件编码、工作区编码、控制台编码、JVM 编码、容器编码、数据库编码任何一个环节不一致都会导致乱码。最有效的排查思路永远是先搞清楚数据从哪来、流向哪去、中间经过了哪些转换环节把整个链路梳理清楚后再一个个检查各环节的编码配置。我个人在项目里的做法是新项目建立的第一步就把 Eclipse 工作区编码、Maven 编码、Git 换行符全部统一为 UTF-8并且在团队文档里写明编码规范。后续团队成员拉取代码、编译、部署都不会因为编码问题浪费额外时间。如果你现在正好被 Eclipse 中文乱码困扰建议先按照文章里的速查表定位问题场景再针对性操作。大多数情况下全局工作区改成 UTF-8 加 Run Configurations 加 VM 参数这两步就能覆盖绝大部分问题。如果还不行就用 Notepad 检查文件真实编码再配合项目级编码设置基本没有解决不了的乱码。最后再提醒一句乱码问题处理过程中一定要先确认编辑器里显示正常再进行另存为转换否则操作不当还可能把原始文件内容弄丢得不偿失。
