上周有同事跑过来问SpringBoot项目里application.properties直接写了中文Value拿到的值全是问号怎么调都调不对。这种问题在开发群里隔三差五就会出现表面上只是“中文乱码”背后其实牵涉源文件编码、构建工具默认字符集、JVM运行编码三层因素。这篇文章就把实际排查过程完整拆一遍讲清楚SpringBoot读取properties中文乱码的解决方案同时覆盖本地开发、Maven/Gradle打包、服务器部署三类最常见场景。适合刚入门SpringBoot的同学也适合处理过问题但没时间把思路捋顺的老手。1. 先从复现乱码现场开始把原因拆干净1.1 一个最简单的乱码现场先看一个典型的例子。某个SpringBoot工程里application.properties写了几行app.name项目管理系统 app.hostlocalhost app.desc默认管理员账号为admin在启动类里用Value注入Component public class AppProperties { Value(${app.name}) private String appName; Value(${app.desc}) private String appDesc; }正常预期是启动后打印出“项目管理系统”“默认管理员账号为admin”但很多人的控制台输出是appName?????? appDesc项箮管çç³»ç»?更夸张的情况是输出一长串“锟斤拷”或者“锟斤讹”。这种乱码出现的位置不同原因完全不一样。如果IDEA里直接跑SpringBoot出现乱码大概率是源文件保存编码和IDE读取编码不一致如果本地正常打包部署到Linux后乱码就要考虑构建阶段或JVM运行环境的问题。先把“现象”定位清楚再去动配置才不会改一通最后发现改错了地方。1.2 Java的Properties格式天生带着历史包袱大多数人知道Java的Properties文件是键值对格式但没注意到它的编码规则。老版本的java.util.Properties在调用load(InputStream)方法读取文件时默认按ISO-8859-1字符集解析。ISO-8859-1本质上是单字节编码只覆盖拉丁语系字符中文不在它的范围内。所以早期Java规范要求Properties文件中如果包含非Latin字符必须写成Unicode转义形式也就是\u4e2d\u6587这样的形式否则读出来就是乱码。这算是Java从JDK 1.0时代带出来的历史包袱。后来JDK提供了load(Reader)方法允许通过Reader指定字符集但很多基础库和工具类仍然沿用load(InputStream)的老路径。SpringBoot和Spring Framework加载配置文件时不同版本对编码的处理细节也有差异这就导致“同样的代码在不同JDK版本或者不同SpringBoot版本下表现不一样”。很多人只改了一处编码设置换台电脑又乱正是因为没理解这层兼容性问题。1.3 乱码产生的三个关键层面要系统性解决SpringBoot读取properties中文乱码不能只盯着某一个设置。我把问题拆成三层源文件保存编码properties文件在磁盘上到底是以UTF-8、GBK还是别的编码存的IDE打开时展示正常不代表文件字节真的符合你的预期。构建阶段编码Maven或Gradle在复制、过滤resources资源时可能会用系统默认编码重新读取文件导致打包进jar的properties已经不是开发时那份字节。运行阶段JVM编码Spring容器里的文件读取、控制台输出、日志输出都受JVM默认字符集影响。Linux系统如果没有设置UTF-8的locale或者启动命令没有指定-Dfile.encodingUTF-8也容易出现乱码。可以这样理解源文件编码相当于原材料构建阶段编码相当于加工过程运行环境编码相当于交付运输。任何一环出现错位最终到业务代码里就是一堆乱码。下面几个章节会分别针对这三层给出可落地的操作。2. 先做兜底把工程编码统一成UTF-82.1 IDEA和Eclipse的编码设置不能只改一处IDEA是目前SpringBoot项目最常用的IDE它的编码设置默认有多个位置。很多人只改了Settings - Editor - File Encodings里的Global Encoding结果项目还是乱因为下面还有Project Encoding、Default encoding for properties files这两个选项。最稳妥的做法是把这三处统一改成UTF-8Global EncodingUTF-8Project EncodingUTF-8Default encoding for properties filesUTF-8同时建议在Default encoding for properties files旁边勾选Transparent native-to-ascii conversion。这个选项勾选后IDEA会在编辑器里显示中文但保存到磁盘时自动转成\uXXXX转义形式这能直接规避Properties历史包袱。这个我在第3章会详细展开。Eclipse用户则要检查Window - Preferences - General - Workspace - Text file encoding以及项目的Resource编码尽量统一成UTF-8。Eclipse老项目默认是GBK如果混用很容易让properties文件在无意间被保存成GBK。除了IDE界面设置我建议在项目根目录放一个.editorconfig文件把properties、java、yml等文件的编码规则显式声明出来。这样不管谁用什么编辑器打开项目IDE都会尽量遵循统一规则。root true [*] charset utf-8 [*.properties] charset utf-8 end_of_line lf这个文件本身不参与编译主要价值是让团队成员提交代码时不会因为个人IDE偏好搞出编码差异。2.2 Maven里必须显式声明sourceEncodingMaven构建SpringBoot项目时如果pom.xml里没有显式声明编码编译器会使用操作系统平台的默认字符集。Windows中文系统默认是GBKLinux默认可能是UTF-8这就导致同一个项目在不同机器上打出不同的结果。所以第一步是在pom.xml的properties节点下加上properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /propertiesproject.build.sourceEncoding主要影响Java源码编译时的-encoding参数project.reporting.outputEncoding影响报告输出。对于资源文件Maven资源和编译插件在处理复制过滤时也会优先读取这个属性作为默认字符集。如果项目里使用maven-resources-plugin做资源过滤比如把properties里的version替换成版本号需要确保插件使用的编码是UTF-8plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId configuration encodingUTF-8/encoding /configuration /plugin这里特别提醒不要只设project.build.sourceEncoding资源插件编码也要一并确认。我有一次就是只加了sourceEncodingproperties文件里的中文在本地正常但发版到测试环境后出现了小范围乱码最后发现是资源过滤插件把文件重新处理过一次。2.3 Gradle项目的等效配置如果你用的是Gradle等价配置如下tasks.withType(JavaCompile) { options.encoding UTF-8 } processResources { filesMatching(**/*.properties) { charset UTF-8 } }charset配置会让Gradle在复制和过滤properties资源时按UTF-8处理。如果不加Gradle在某些环境下会按系统平台的默认字符集走和Maven犯同样的毛病。另外Gradle守护进程的JVM参数也可能影响但通常只要上面两处配置好资源编码就不会有太大问题。如果项目用了io.spring.dependency-management插件或SpringBoot Gradle插件记得这些插件本身不影响资源编码还是要靠processResources来兜底。2.4 运行时的JVM参数和系统语言环境前面两个小节解决的是“文件进jar之前”的编码问题。真正到运行时JVM默认字符集如果不对读取序列化和控制台输出仍然可能乱。最直接的做法是在启动命令里显式指定java -Dfile.encodingUTF-8 -Duser.languagezh -Duser.countryCN -jar app.jar生产环境的Linux服务器可以先检查echo $LANG locale如果输出不是UTF-8相关需要修改环境变量或者在启动脚本里临时设置export LANGzh_CN.UTF-8 export LC_ALLzh_CN.UTF-8JDK 18以后file.encoding默认就是UTF-8相关问题会少很多但旧版本JDK仍然需要显式指定。如果你的项目还在用JDK 8或11别偷懒启动脚本里加上参数最安心。3. 治本策略让properties文件自带乱码免疫体质3.1 为什么Unicode转义是Properties最稳妥的形态既然老版Properties默认按ISO-8859-1解析那最稳妥的思路就是让properties文件只包含ASCII字符中文内容全部转成\uXXXX这种Unicode转义序列。无论你的文件在Windows、Linux、macOS之间怎么拷贝只要文件本身是纯ASCII字节读取时就不会产生编码错乱。比如app.name\u9879\u76ee\u7ba1\u7406\u7cfb\u7edf这串看似乱码的东西在Java的Properties里读取后依然还原成“项目管理系统”。这种方式不依赖外部环境属于从根上规避问题。3.2 IDEA的Transparent native-to-ascii conversion是最大杀器上一章提到在IDEA的File Encodings设置里勾选Transparent native-to-ascii conversion后你会在IDEA编辑器里看到正常中文但保存时IDEA自动把中文转成\uXXXX。这个机制照顾了两边人看到的是可读中文磁盘上保存的是纯ASCII字符。实际操作要点设置路径Settings - Editor - File Encodings。勾选Default encoding for properties files为UTF-8同时勾选Transparent native-to-ascii conversion。已经存在的properties文件如果里面是未转义的中文需要手动操作一下才会变成转义形态。可以全选内容剪切后粘贴回来IDEA通常会把中文转成\uXXXX。如果文件已经在磁盘上被保存成UTF-8且没有转义也可以不勾选这个选项直接保持UTF-8存储再配合后续第4章的方式读取。但那样对运行环境的依赖更强。有一类情况需要特别注意IDEA显示和实际存储可能不一致。如果你把文件提交到Git然后在命令行用cat查看会发现文件内容是一堆\uXXXX。这完全正常不代表文件坏了。3.3 批量转换已有乱码文件如果你手头已经有一堆带着中文的properties文件想统一转成Unicode转义形态最简单的是用JDK自带的native2ascii命令。在JDK安装目录的bin下可以找到这个工具。用法native2ascii -encoding UTF-8 source.properties target.properties假设你的源文件是UTF-8编码的中文执行后target.properties里就会是转义后的ASCII内容。想覆盖原文件可以先在同一目录生成新文件再替换。如果是Windows并且项目里文件比较多可以用一个小循环for /r %i in (*.properties) do native2ascii -encoding UTF-8 %i %i.tmp move /y %i.tmp %imacOS或Linux则可以用find配合while循环find . -name *.properties -exec sh -c native2ascii -encoding UTF-8 $1 $1.tmp mv $1.tmp $1 _ {} \;需要注意转换前最好备份原文件或者确认已经提交Git因为该操作会重写文件内容。转换完成后用git diff查看你会发现中文全部变成了\uXXXX这是预期效果。3.4 转义文件之后的日常维护体会把properties文件转成Unicode转义形态后最大的缺点是“外人直接打开文件看到的是不可读内容”。这时候我们可以换个思路开发时以IDEA界面为准日常阅读用IDEA打开如果非得用命令行看内容用native2ascii -reverse还原成中文视图或者直接写个小脚本。在团队协作中更推荐把“使用IDEA透明转换”作为强制约定而不是要求所有人都手动维护\uXXXX。这样做的好处是乱码概率几乎降为零代价是Code Review时看到的是转义序列不太直观。另外一个伴随好处是properties文件转成ASCII后不再依赖Maven/Gradle的charset配置。即使构建环境没有显式指定UTF-8文件里的中文也不会被改动因为ASCII在任何编码体系下解释结果都一样。4. 更省心的路径用YAML或显式指定编码加载4.1 直接换成application.yml能少一大半问题SpringBoot本身完全支持application.ymlYAML文件不存在Properties那种ISO-8859-1历史包袱SpringBoot在解析时通常按UTF-8读取。所以如果项目允许最省事的方案就是直接使用YAML作为主配置。app: name: 项目管理系统 host: localhost desc: 默认管理员账号为admin对应的Java读取逻辑完全不用改Value、ConfigurationProperties照常工作。从我个人实际经验看把一批properties改成yml之后中文乱码现象几乎绝迹特别是部署到容器里时少了很多奇奇怪怪的编码问题。不过要注意某些第三方库或者老项目会强制读取固定的properties文件名这时直接换yml不一定可行。这种情况下可以保留application.properties作为牵引文件把具体的中文配置迁移到yml中会带来双配置文件的坑不推荐。优先选择是下面这类显式指定编码的方案。4.2 PropertySource可以直接指定UTF-8Spring的PropertySource注解里有一个encoding属性用来指定properties文件的字符集。这大概是“不改文件格式”前提下最直接的解决方案。Configuration PropertySource(value classpath:myconfig.properties, encoding UTF-8) public class MyConfig { }如果项目里有多份properties可以用数组指定多个文件PropertySource( value { classpath:db.properties, classpath:app.properties }, encoding UTF-8 ) public class MyConfig { }这里要注意优先级问题。PropertySource加载的属性会进入Spring Environment但如果你同时又让SpringBoot自动扫描application.properties同名的key可能出现覆盖。建议把需要中文的配置放到独立的properties文件里通过PropertySource引入避免和默认application.properties重复。另外PropertySource的encoding属性在Spring Framework 4.3之后才稳定可用SpringBoot 1.x旧版本要确认框架版本是否够新。现代项目基本不用担心。4.3 自己封装一个UTF-8读取的Properties工具类如果不想让业务代码依赖Spring的PropertySource可以自己写一个简单的工具类按UTF-8读取properties文件。import org.springframework.core.io.ClassPathResource; import org.springframework.util.StringUtils; import java.io.IOException; import java.io.InputStreamReader; import java.io.Reader; import java.nio.charset.StandardCharsets; import java.util.Properties; public class Utf8PropertiesUtil { public static Properties load(String classpathFile) throws IOException { Properties properties new Properties(); ClassPathResource resource new ClassPathResource(classpathFile); try (Reader reader new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8)) { properties.load(reader); } return properties; } public static String get(String classpathFile, String key) throws IOException { Properties properties load(classpathFile); return StringUtils.hasText(properties.getProperty(key)) ? properties.getProperty(key) : null; } }调用方式Properties props Utf8PropertiesUtil.load(custom.properties); String title props.getProperty(title);核心逻辑就是Properties.load(Reader)Reader显式使用UTF-8这样源文件以UTF-8编码保存时就能正确读出中文。注意这段代码依赖Spring的ClassPathResource如果你不想引Spring依赖也可以自己写getResourceAsStream再包装Reader。这种方式的优点是完全可控缺点是丢失了Spring Boot原生配置覆盖机制。所以一般只用于读取那些非业务性的、固定的静态配置比如第三方SDK参数、模板文件参数等。4.4 放在数据库或配置中心里让配置脱离文件编码大型项目里纯中文类配置越来越多还有人喜欢在配置里写一大堆中文提示语这些内容放在properties里本身就是一种折磨。更合理的路径是把它们挪到配置中心或数据库表中比如Nacos、Apollo或者自己的参数表。原因很简单数据库和配置中心返回的是字符串数据根本不经过文件编码解析也就不存在“properties中文乱码”这回事。例如把“项目管理系统”这种显示名称存到数据库配置表里启动时通过ConfigurationProperties绑定到一个ConfigBean或者通过一个ConfigService查询。这种方式对开发人员来说还能顺便解决配置动态刷新问题属于一石二鸟。但它不适合零基础小项目因为引入配置中心有额外的运维成本。如果是个人学习项目或者小团队内部项目直接用YAML或Unicode转义就够了。5. 部署到服务器后仍然乱码按照这个顺序排查5.1 本地运行正常打包上服务器后乱码这是排查工作量最大的一种场景。先不要盲改代码把jar包解压出来看里面的properties文件本身是否正常。jar xf app.jar BOOT-INF/classes/application.properties file BOOT-INF/classes/application.properties xxd BOOT-INF/classes/application.properties | head如果file输出显示文件是UTF-8并且xxd看到的字节流里中文是正常UTF-8字节说明构建阶段没问题问题出在服务器运行时。下一步查看服务器环境变量echo $LANG locale java -version如果LANG不是UTF-8按上一章说的在启动脚本里设置环境变量或者启动命令加-Dfile.encodingUTF-8。如果file显示文件是GBK或ISO-8859-1说明Maven/Gradle打包阶段已经把文件改坏了回到第2章去检查资源插件编码。5.2 Docker容器里的中文乱码Docker部署SpringBoot时容器基础镜像如果比较精简可能没有安装中文字符集Java进程即使读出正确的中文写到控制台或者日志里也可能变成问号。推荐在Dockerfile里显式设置ENV LANGC.UTF-8 ENV JAVA_TOOL_OPTIONS-Dfile.encodingUTF-8JAVA_TOOL_OPTIONS会被Java虚拟机自动读取等于把启动参数写进环境变量。虽然它也会输出一条“Picked up JAVA_TOOL_OPTIONS”日志但总比中文乱码好。如果基础镜像是基于Debian的还可以安装locales包RUN apt-get update apt-get install -y locales locale-gen zh_CN.UTF-8 ENV LANGzh_CN.UTF-8但不建议为了输出中文特意去装中文字符集纯UTF-8环境已经够用。关键是保持全链路UTF-8一致。5.3 快速确认到底是存储乱码还是显示乱码有时程序读到的字符串是对的只是控制台显示乱码这种最容易被误判。区分方法很简单把字符串写入日志文件再用支持UTF-8的编辑器打开。如果日志文件里中文正常说明是控制台显示端问题。Windows的CMD默认GBKIDEA的Console可能也受了系统默认编码影响。如果日志文件里已经是乱码那就是读取/转换阶段出了问题需要继续查配置文件编码和JVM编码。在IDEA里可以在启动配置的VM options加-Dfile.encodingUTF-8并设置Run - Edit Configurations - Environment variables里的LANGzh_CN.UTF-8或者直接设置Help - Edit Custom VM Options在idea.vmoptions里增加-Dfile.encodingUTF-8这能改善开发机控制台输出。5.4 不要把HTTP请求参数乱码混进来SpringBoot项目里还有一类常见乱码是前端请求参数乱码比如POST表单里提交中文后端收到后是乱码。这和properties文件乱码是两回事。请求参数乱码通常靠Spring Boot的编码过滤器解决server.servlet.encoding.charsetUTF-8 server.servlet.encoding.enabledtrue server.servlet.encoding.forcetrue老一点的SpringBoot用spring.http.encoding.charsetUTF-8 spring.http.encoding.enabledtrue spring.http.encoding.forcetrue排查时如果发现自己明明改了properties编码结果还是乱码先确认问题到底出在“读取配置”还是“接收请求”。两者混在一起查会非常浪费时间我在项目里见过的编码事故至少有一半是因为定位错对象。6. 常见问题与避坑清单6.1 问题速查表下面这张表整理了几种典型场景、可能原因和处理办法可以直接截图放到团队知识库里现象可能原因处理办法IDEA里写中文运行后Value得到乱码文件保存编码与读取编码不一致统一IDE编码为UTF-8或开启Transparent native-to-asciiconsistencyIDE显示正常但部署到Linux后乱码构建阶段资源插件用错编码pom.xml/Gradle配置UTF-8检查jar内文件bytes控制台打印中文正常日志文件乱码日志框架或系统字符集不一致设置JVM-Dfile.encodingUTF-8检查日志接收端编码容器里中文全部变成问号基础镜像缺少中文字符集或LANG环境变量不对Dockerfile里设置LANGC.UTF-8或安装localesPropertySource加载中文properties乱码注解未指定encoding添加encoding UTF-8使用GBK工程历史代码乱码严重历史项目编码混乱分步迁移为UTF-8优先处理配置类和properties同一个项目在别人机器正常我这乱码个人IDE或系统locale问题检查IDE编码、Maven编码、系统LANG6.2 一个容易忽略的坑properties文件里写中文注释很多人只注意配置值却忽略properties文件里的中文注释。虽然注释不影响运行但一旦构建工具把文件从GBK转成UTF-8注释里的中文可能被转成非法字节某些极端情况下会导致Properties.load解析失败整个文件读不出来。我有一次就踩过这个坑一个老的properties文件里全是中文注释开发机是WindowsMaven构建时资源插件用了GBK过滤结果打包到Linux后文件开头出现了一个非法字符SpringBoot启动时报Malformed \uxxxx encoding。看起来和中文乱码无关实际上是编码转换惹的祸。所以统一编码时不光要关注键值对还要把注释一并处理。最简单的方式是中文注释要么也转成Unicode转义要么干脆换成英文。维护成本低还能避免很多潜在问题。6.3 用CI流水线从源头拦截乱码团队里人多的时候单靠某个开发者的IDE设置并不可靠。我们可以在CI流程里加一条简单检查扫描代码仓库里的properties文件如果存在未转义的非ASCII字符就提示构建失败或警告。以Linux环境为例可以用下面的命令快速找出包含裸中文的properties文件grep -rlP [^\x00-\x7F] --include*.properties .再用file命令确认这些文件的编码是否真是UTF-8find . -name *.properties -exec file -bi {} \; | grep -v utf-8 | head如果项目决定全面使用“所有properties纯ASCII”的策略那只要CI里发现非ASCII字符就报警让人改成Unicode转义或改用YAML。这个检查成本很低一劳永逸很适合持续维护的项目。还可以配合.gitattributes设置properties文件的语言让Git在合并冲突时尽量不产生编码层面的乱跳*.properties text eollf这些都属于工程规范层面的“防患于未然”。说实话中文乱码技术含量不高但重复出现很耗人精神提前用流程堵住是最聪明的做法。结尾前的一点经验处理这类乱码多了之后我最大的体会是不要迷信“某一个配置项能一劳永逸”。编码问题本质上是一条链路源文件编码、构建编码、运行编码三个环节必须都对齐才真正可靠。如果时间特别紧优先用PropertySource(encoding UTF-8)快速止血如果项目还在早期尽量用YAML替代properties如果团队规模大建议直接把properties统一转成Unicode转义并在CI里加检查。最后再分享一个小技巧排查乱码时先把文件用xxd或hexdump看字节再对照实际输出立刻能判断是存错了还是读错了。脚本写多了之后你会发现80%的乱码问题在20秒内就能定位到根因剩下的不过是按上面这些方案逐项修正而已。
SpringBoot properties中文乱码？从编码原理到工程实践全解
上周有同事跑过来问SpringBoot项目里application.properties直接写了中文Value拿到的值全是问号怎么调都调不对。这种问题在开发群里隔三差五就会出现表面上只是“中文乱码”背后其实牵涉源文件编码、构建工具默认字符集、JVM运行编码三层因素。这篇文章就把实际排查过程完整拆一遍讲清楚SpringBoot读取properties中文乱码的解决方案同时覆盖本地开发、Maven/Gradle打包、服务器部署三类最常见场景。适合刚入门SpringBoot的同学也适合处理过问题但没时间把思路捋顺的老手。1. 先从复现乱码现场开始把原因拆干净1.1 一个最简单的乱码现场先看一个典型的例子。某个SpringBoot工程里application.properties写了几行app.name项目管理系统 app.hostlocalhost app.desc默认管理员账号为admin在启动类里用Value注入Component public class AppProperties { Value(${app.name}) private String appName; Value(${app.desc}) private String appDesc; }正常预期是启动后打印出“项目管理系统”“默认管理员账号为admin”但很多人的控制台输出是appName?????? appDesc项箮管çç³»ç»?更夸张的情况是输出一长串“锟斤拷”或者“锟斤讹”。这种乱码出现的位置不同原因完全不一样。如果IDEA里直接跑SpringBoot出现乱码大概率是源文件保存编码和IDE读取编码不一致如果本地正常打包部署到Linux后乱码就要考虑构建阶段或JVM运行环境的问题。先把“现象”定位清楚再去动配置才不会改一通最后发现改错了地方。1.2 Java的Properties格式天生带着历史包袱大多数人知道Java的Properties文件是键值对格式但没注意到它的编码规则。老版本的java.util.Properties在调用load(InputStream)方法读取文件时默认按ISO-8859-1字符集解析。ISO-8859-1本质上是单字节编码只覆盖拉丁语系字符中文不在它的范围内。所以早期Java规范要求Properties文件中如果包含非Latin字符必须写成Unicode转义形式也就是\u4e2d\u6587这样的形式否则读出来就是乱码。这算是Java从JDK 1.0时代带出来的历史包袱。后来JDK提供了load(Reader)方法允许通过Reader指定字符集但很多基础库和工具类仍然沿用load(InputStream)的老路径。SpringBoot和Spring Framework加载配置文件时不同版本对编码的处理细节也有差异这就导致“同样的代码在不同JDK版本或者不同SpringBoot版本下表现不一样”。很多人只改了一处编码设置换台电脑又乱正是因为没理解这层兼容性问题。1.3 乱码产生的三个关键层面要系统性解决SpringBoot读取properties中文乱码不能只盯着某一个设置。我把问题拆成三层源文件保存编码properties文件在磁盘上到底是以UTF-8、GBK还是别的编码存的IDE打开时展示正常不代表文件字节真的符合你的预期。构建阶段编码Maven或Gradle在复制、过滤resources资源时可能会用系统默认编码重新读取文件导致打包进jar的properties已经不是开发时那份字节。运行阶段JVM编码Spring容器里的文件读取、控制台输出、日志输出都受JVM默认字符集影响。Linux系统如果没有设置UTF-8的locale或者启动命令没有指定-Dfile.encodingUTF-8也容易出现乱码。可以这样理解源文件编码相当于原材料构建阶段编码相当于加工过程运行环境编码相当于交付运输。任何一环出现错位最终到业务代码里就是一堆乱码。下面几个章节会分别针对这三层给出可落地的操作。2. 先做兜底把工程编码统一成UTF-82.1 IDEA和Eclipse的编码设置不能只改一处IDEA是目前SpringBoot项目最常用的IDE它的编码设置默认有多个位置。很多人只改了Settings - Editor - File Encodings里的Global Encoding结果项目还是乱因为下面还有Project Encoding、Default encoding for properties files这两个选项。最稳妥的做法是把这三处统一改成UTF-8Global EncodingUTF-8Project EncodingUTF-8Default encoding for properties filesUTF-8同时建议在Default encoding for properties files旁边勾选Transparent native-to-ascii conversion。这个选项勾选后IDEA会在编辑器里显示中文但保存到磁盘时自动转成\uXXXX转义形式这能直接规避Properties历史包袱。这个我在第3章会详细展开。Eclipse用户则要检查Window - Preferences - General - Workspace - Text file encoding以及项目的Resource编码尽量统一成UTF-8。Eclipse老项目默认是GBK如果混用很容易让properties文件在无意间被保存成GBK。除了IDE界面设置我建议在项目根目录放一个.editorconfig文件把properties、java、yml等文件的编码规则显式声明出来。这样不管谁用什么编辑器打开项目IDE都会尽量遵循统一规则。root true [*] charset utf-8 [*.properties] charset utf-8 end_of_line lf这个文件本身不参与编译主要价值是让团队成员提交代码时不会因为个人IDE偏好搞出编码差异。2.2 Maven里必须显式声明sourceEncodingMaven构建SpringBoot项目时如果pom.xml里没有显式声明编码编译器会使用操作系统平台的默认字符集。Windows中文系统默认是GBKLinux默认可能是UTF-8这就导致同一个项目在不同机器上打出不同的结果。所以第一步是在pom.xml的properties节点下加上properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /propertiesproject.build.sourceEncoding主要影响Java源码编译时的-encoding参数project.reporting.outputEncoding影响报告输出。对于资源文件Maven资源和编译插件在处理复制过滤时也会优先读取这个属性作为默认字符集。如果项目里使用maven-resources-plugin做资源过滤比如把properties里的version替换成版本号需要确保插件使用的编码是UTF-8plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId configuration encodingUTF-8/encoding /configuration /plugin这里特别提醒不要只设project.build.sourceEncoding资源插件编码也要一并确认。我有一次就是只加了sourceEncodingproperties文件里的中文在本地正常但发版到测试环境后出现了小范围乱码最后发现是资源过滤插件把文件重新处理过一次。2.3 Gradle项目的等效配置如果你用的是Gradle等价配置如下tasks.withType(JavaCompile) { options.encoding UTF-8 } processResources { filesMatching(**/*.properties) { charset UTF-8 } }charset配置会让Gradle在复制和过滤properties资源时按UTF-8处理。如果不加Gradle在某些环境下会按系统平台的默认字符集走和Maven犯同样的毛病。另外Gradle守护进程的JVM参数也可能影响但通常只要上面两处配置好资源编码就不会有太大问题。如果项目用了io.spring.dependency-management插件或SpringBoot Gradle插件记得这些插件本身不影响资源编码还是要靠processResources来兜底。2.4 运行时的JVM参数和系统语言环境前面两个小节解决的是“文件进jar之前”的编码问题。真正到运行时JVM默认字符集如果不对读取序列化和控制台输出仍然可能乱。最直接的做法是在启动命令里显式指定java -Dfile.encodingUTF-8 -Duser.languagezh -Duser.countryCN -jar app.jar生产环境的Linux服务器可以先检查echo $LANG locale如果输出不是UTF-8相关需要修改环境变量或者在启动脚本里临时设置export LANGzh_CN.UTF-8 export LC_ALLzh_CN.UTF-8JDK 18以后file.encoding默认就是UTF-8相关问题会少很多但旧版本JDK仍然需要显式指定。如果你的项目还在用JDK 8或11别偷懒启动脚本里加上参数最安心。3. 治本策略让properties文件自带乱码免疫体质3.1 为什么Unicode转义是Properties最稳妥的形态既然老版Properties默认按ISO-8859-1解析那最稳妥的思路就是让properties文件只包含ASCII字符中文内容全部转成\uXXXX这种Unicode转义序列。无论你的文件在Windows、Linux、macOS之间怎么拷贝只要文件本身是纯ASCII字节读取时就不会产生编码错乱。比如app.name\u9879\u76ee\u7ba1\u7406\u7cfb\u7edf这串看似乱码的东西在Java的Properties里读取后依然还原成“项目管理系统”。这种方式不依赖外部环境属于从根上规避问题。3.2 IDEA的Transparent native-to-ascii conversion是最大杀器上一章提到在IDEA的File Encodings设置里勾选Transparent native-to-ascii conversion后你会在IDEA编辑器里看到正常中文但保存时IDEA自动把中文转成\uXXXX。这个机制照顾了两边人看到的是可读中文磁盘上保存的是纯ASCII字符。实际操作要点设置路径Settings - Editor - File Encodings。勾选Default encoding for properties files为UTF-8同时勾选Transparent native-to-ascii conversion。已经存在的properties文件如果里面是未转义的中文需要手动操作一下才会变成转义形态。可以全选内容剪切后粘贴回来IDEA通常会把中文转成\uXXXX。如果文件已经在磁盘上被保存成UTF-8且没有转义也可以不勾选这个选项直接保持UTF-8存储再配合后续第4章的方式读取。但那样对运行环境的依赖更强。有一类情况需要特别注意IDEA显示和实际存储可能不一致。如果你把文件提交到Git然后在命令行用cat查看会发现文件内容是一堆\uXXXX。这完全正常不代表文件坏了。3.3 批量转换已有乱码文件如果你手头已经有一堆带着中文的properties文件想统一转成Unicode转义形态最简单的是用JDK自带的native2ascii命令。在JDK安装目录的bin下可以找到这个工具。用法native2ascii -encoding UTF-8 source.properties target.properties假设你的源文件是UTF-8编码的中文执行后target.properties里就会是转义后的ASCII内容。想覆盖原文件可以先在同一目录生成新文件再替换。如果是Windows并且项目里文件比较多可以用一个小循环for /r %i in (*.properties) do native2ascii -encoding UTF-8 %i %i.tmp move /y %i.tmp %imacOS或Linux则可以用find配合while循环find . -name *.properties -exec sh -c native2ascii -encoding UTF-8 $1 $1.tmp mv $1.tmp $1 _ {} \;需要注意转换前最好备份原文件或者确认已经提交Git因为该操作会重写文件内容。转换完成后用git diff查看你会发现中文全部变成了\uXXXX这是预期效果。3.4 转义文件之后的日常维护体会把properties文件转成Unicode转义形态后最大的缺点是“外人直接打开文件看到的是不可读内容”。这时候我们可以换个思路开发时以IDEA界面为准日常阅读用IDEA打开如果非得用命令行看内容用native2ascii -reverse还原成中文视图或者直接写个小脚本。在团队协作中更推荐把“使用IDEA透明转换”作为强制约定而不是要求所有人都手动维护\uXXXX。这样做的好处是乱码概率几乎降为零代价是Code Review时看到的是转义序列不太直观。另外一个伴随好处是properties文件转成ASCII后不再依赖Maven/Gradle的charset配置。即使构建环境没有显式指定UTF-8文件里的中文也不会被改动因为ASCII在任何编码体系下解释结果都一样。4. 更省心的路径用YAML或显式指定编码加载4.1 直接换成application.yml能少一大半问题SpringBoot本身完全支持application.ymlYAML文件不存在Properties那种ISO-8859-1历史包袱SpringBoot在解析时通常按UTF-8读取。所以如果项目允许最省事的方案就是直接使用YAML作为主配置。app: name: 项目管理系统 host: localhost desc: 默认管理员账号为admin对应的Java读取逻辑完全不用改Value、ConfigurationProperties照常工作。从我个人实际经验看把一批properties改成yml之后中文乱码现象几乎绝迹特别是部署到容器里时少了很多奇奇怪怪的编码问题。不过要注意某些第三方库或者老项目会强制读取固定的properties文件名这时直接换yml不一定可行。这种情况下可以保留application.properties作为牵引文件把具体的中文配置迁移到yml中会带来双配置文件的坑不推荐。优先选择是下面这类显式指定编码的方案。4.2 PropertySource可以直接指定UTF-8Spring的PropertySource注解里有一个encoding属性用来指定properties文件的字符集。这大概是“不改文件格式”前提下最直接的解决方案。Configuration PropertySource(value classpath:myconfig.properties, encoding UTF-8) public class MyConfig { }如果项目里有多份properties可以用数组指定多个文件PropertySource( value { classpath:db.properties, classpath:app.properties }, encoding UTF-8 ) public class MyConfig { }这里要注意优先级问题。PropertySource加载的属性会进入Spring Environment但如果你同时又让SpringBoot自动扫描application.properties同名的key可能出现覆盖。建议把需要中文的配置放到独立的properties文件里通过PropertySource引入避免和默认application.properties重复。另外PropertySource的encoding属性在Spring Framework 4.3之后才稳定可用SpringBoot 1.x旧版本要确认框架版本是否够新。现代项目基本不用担心。4.3 自己封装一个UTF-8读取的Properties工具类如果不想让业务代码依赖Spring的PropertySource可以自己写一个简单的工具类按UTF-8读取properties文件。import org.springframework.core.io.ClassPathResource; import org.springframework.util.StringUtils; import java.io.IOException; import java.io.InputStreamReader; import java.io.Reader; import java.nio.charset.StandardCharsets; import java.util.Properties; public class Utf8PropertiesUtil { public static Properties load(String classpathFile) throws IOException { Properties properties new Properties(); ClassPathResource resource new ClassPathResource(classpathFile); try (Reader reader new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8)) { properties.load(reader); } return properties; } public static String get(String classpathFile, String key) throws IOException { Properties properties load(classpathFile); return StringUtils.hasText(properties.getProperty(key)) ? properties.getProperty(key) : null; } }调用方式Properties props Utf8PropertiesUtil.load(custom.properties); String title props.getProperty(title);核心逻辑就是Properties.load(Reader)Reader显式使用UTF-8这样源文件以UTF-8编码保存时就能正确读出中文。注意这段代码依赖Spring的ClassPathResource如果你不想引Spring依赖也可以自己写getResourceAsStream再包装Reader。这种方式的优点是完全可控缺点是丢失了Spring Boot原生配置覆盖机制。所以一般只用于读取那些非业务性的、固定的静态配置比如第三方SDK参数、模板文件参数等。4.4 放在数据库或配置中心里让配置脱离文件编码大型项目里纯中文类配置越来越多还有人喜欢在配置里写一大堆中文提示语这些内容放在properties里本身就是一种折磨。更合理的路径是把它们挪到配置中心或数据库表中比如Nacos、Apollo或者自己的参数表。原因很简单数据库和配置中心返回的是字符串数据根本不经过文件编码解析也就不存在“properties中文乱码”这回事。例如把“项目管理系统”这种显示名称存到数据库配置表里启动时通过ConfigurationProperties绑定到一个ConfigBean或者通过一个ConfigService查询。这种方式对开发人员来说还能顺便解决配置动态刷新问题属于一石二鸟。但它不适合零基础小项目因为引入配置中心有额外的运维成本。如果是个人学习项目或者小团队内部项目直接用YAML或Unicode转义就够了。5. 部署到服务器后仍然乱码按照这个顺序排查5.1 本地运行正常打包上服务器后乱码这是排查工作量最大的一种场景。先不要盲改代码把jar包解压出来看里面的properties文件本身是否正常。jar xf app.jar BOOT-INF/classes/application.properties file BOOT-INF/classes/application.properties xxd BOOT-INF/classes/application.properties | head如果file输出显示文件是UTF-8并且xxd看到的字节流里中文是正常UTF-8字节说明构建阶段没问题问题出在服务器运行时。下一步查看服务器环境变量echo $LANG locale java -version如果LANG不是UTF-8按上一章说的在启动脚本里设置环境变量或者启动命令加-Dfile.encodingUTF-8。如果file显示文件是GBK或ISO-8859-1说明Maven/Gradle打包阶段已经把文件改坏了回到第2章去检查资源插件编码。5.2 Docker容器里的中文乱码Docker部署SpringBoot时容器基础镜像如果比较精简可能没有安装中文字符集Java进程即使读出正确的中文写到控制台或者日志里也可能变成问号。推荐在Dockerfile里显式设置ENV LANGC.UTF-8 ENV JAVA_TOOL_OPTIONS-Dfile.encodingUTF-8JAVA_TOOL_OPTIONS会被Java虚拟机自动读取等于把启动参数写进环境变量。虽然它也会输出一条“Picked up JAVA_TOOL_OPTIONS”日志但总比中文乱码好。如果基础镜像是基于Debian的还可以安装locales包RUN apt-get update apt-get install -y locales locale-gen zh_CN.UTF-8 ENV LANGzh_CN.UTF-8但不建议为了输出中文特意去装中文字符集纯UTF-8环境已经够用。关键是保持全链路UTF-8一致。5.3 快速确认到底是存储乱码还是显示乱码有时程序读到的字符串是对的只是控制台显示乱码这种最容易被误判。区分方法很简单把字符串写入日志文件再用支持UTF-8的编辑器打开。如果日志文件里中文正常说明是控制台显示端问题。Windows的CMD默认GBKIDEA的Console可能也受了系统默认编码影响。如果日志文件里已经是乱码那就是读取/转换阶段出了问题需要继续查配置文件编码和JVM编码。在IDEA里可以在启动配置的VM options加-Dfile.encodingUTF-8并设置Run - Edit Configurations - Environment variables里的LANGzh_CN.UTF-8或者直接设置Help - Edit Custom VM Options在idea.vmoptions里增加-Dfile.encodingUTF-8这能改善开发机控制台输出。5.4 不要把HTTP请求参数乱码混进来SpringBoot项目里还有一类常见乱码是前端请求参数乱码比如POST表单里提交中文后端收到后是乱码。这和properties文件乱码是两回事。请求参数乱码通常靠Spring Boot的编码过滤器解决server.servlet.encoding.charsetUTF-8 server.servlet.encoding.enabledtrue server.servlet.encoding.forcetrue老一点的SpringBoot用spring.http.encoding.charsetUTF-8 spring.http.encoding.enabledtrue spring.http.encoding.forcetrue排查时如果发现自己明明改了properties编码结果还是乱码先确认问题到底出在“读取配置”还是“接收请求”。两者混在一起查会非常浪费时间我在项目里见过的编码事故至少有一半是因为定位错对象。6. 常见问题与避坑清单6.1 问题速查表下面这张表整理了几种典型场景、可能原因和处理办法可以直接截图放到团队知识库里现象可能原因处理办法IDEA里写中文运行后Value得到乱码文件保存编码与读取编码不一致统一IDE编码为UTF-8或开启Transparent native-to-asciiconsistencyIDE显示正常但部署到Linux后乱码构建阶段资源插件用错编码pom.xml/Gradle配置UTF-8检查jar内文件bytes控制台打印中文正常日志文件乱码日志框架或系统字符集不一致设置JVM-Dfile.encodingUTF-8检查日志接收端编码容器里中文全部变成问号基础镜像缺少中文字符集或LANG环境变量不对Dockerfile里设置LANGC.UTF-8或安装localesPropertySource加载中文properties乱码注解未指定encoding添加encoding UTF-8使用GBK工程历史代码乱码严重历史项目编码混乱分步迁移为UTF-8优先处理配置类和properties同一个项目在别人机器正常我这乱码个人IDE或系统locale问题检查IDE编码、Maven编码、系统LANG6.2 一个容易忽略的坑properties文件里写中文注释很多人只注意配置值却忽略properties文件里的中文注释。虽然注释不影响运行但一旦构建工具把文件从GBK转成UTF-8注释里的中文可能被转成非法字节某些极端情况下会导致Properties.load解析失败整个文件读不出来。我有一次就踩过这个坑一个老的properties文件里全是中文注释开发机是WindowsMaven构建时资源插件用了GBK过滤结果打包到Linux后文件开头出现了一个非法字符SpringBoot启动时报Malformed \uxxxx encoding。看起来和中文乱码无关实际上是编码转换惹的祸。所以统一编码时不光要关注键值对还要把注释一并处理。最简单的方式是中文注释要么也转成Unicode转义要么干脆换成英文。维护成本低还能避免很多潜在问题。6.3 用CI流水线从源头拦截乱码团队里人多的时候单靠某个开发者的IDE设置并不可靠。我们可以在CI流程里加一条简单检查扫描代码仓库里的properties文件如果存在未转义的非ASCII字符就提示构建失败或警告。以Linux环境为例可以用下面的命令快速找出包含裸中文的properties文件grep -rlP [^\x00-\x7F] --include*.properties .再用file命令确认这些文件的编码是否真是UTF-8find . -name *.properties -exec file -bi {} \; | grep -v utf-8 | head如果项目决定全面使用“所有properties纯ASCII”的策略那只要CI里发现非ASCII字符就报警让人改成Unicode转义或改用YAML。这个检查成本很低一劳永逸很适合持续维护的项目。还可以配合.gitattributes设置properties文件的语言让Git在合并冲突时尽量不产生编码层面的乱跳*.properties text eollf这些都属于工程规范层面的“防患于未然”。说实话中文乱码技术含量不高但重复出现很耗人精神提前用流程堵住是最聪明的做法。结尾前的一点经验处理这类乱码多了之后我最大的体会是不要迷信“某一个配置项能一劳永逸”。编码问题本质上是一条链路源文件编码、构建编码、运行编码三个环节必须都对齐才真正可靠。如果时间特别紧优先用PropertySource(encoding UTF-8)快速止血如果项目还在早期尽量用YAML替代properties如果团队规模大建议直接把properties统一转成Unicode转义并在CI里加检查。最后再分享一个小技巧排查乱码时先把文件用xxd或hexdump看字节再对照实际输出立刻能判断是存错了还是读错了。脚本写多了之后你会发现80%的乱码问题在20秒内就能定位到根因剩下的不过是按上面这些方案逐项修正而已。
