上周有同事跑过来问：SpringBoot项目里application.properties直接写了中文，@Value拿到的值全是问号，怎么调都调不对。这种问题在开发群里隔三差五就会出现，表面上只是“中文乱码”，背后其实牵涉源文件编码、构建工具默认字符集、JVM运行编码三层因素。这篇文章就把实际排查过程完整拆一遍，讲清楚SpringBoot读取properties中文乱码的解决方案，同时覆盖本地开发、Maven/Gradle打包、服务器部署三类最常见场景。适合刚入门SpringBoot的同学，也适合处理过问题但没时间把思路捋顺的老手。

1. 先从复现乱码现场开始，把原因拆干净

1.1 一个最简单的乱码现场

先看一个典型的例子。某个SpringBoot工程里，application.properties写了几行：

app.name=项目管理系统 app.host=localhost 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.encoding=UTF-8，也容易出现乱码。

可以这样理解：源文件编码相当于原材料，构建阶段编码相当于加工过程，运行环境编码相当于交付运输。任何一环出现错位，最终到业务代码里就是一堆乱码。下面几个章节会分别针对这三层给出可落地的操作。

2. 先做兜底：把工程编码统一成UTF-8

2.1 IDEA和Eclipse的编码设置不能只改一处

IDEA是目前SpringBoot项目最常用的IDE，它的编码设置默认有多个位置。很多人只改了Settings -> Editor -> File Encodings里的Global Encoding，结果项目还是乱，因为下面还有Project Encoding、Default encoding for properties files这两个选项。

最稳妥的做法是把这三处统一改成UTF-8：

• Global Encoding：UTF-8
• Project Encoding：UTF-8
• Default encoding for properties files：UTF-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里必须显式声明sourceEncoding

Maven构建SpringBoot项目时，如果pom.xml里没有显式声明编码，编译器会使用操作系统平台的默认字符集。Windows中文系统默认是GBK，Linux默认可能是UTF-8，这就导致同一个项目在不同机器上打出不同的结果。

所以第一步是在pom.xml的properties节点下加上：

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

project.build.sourceEncoding主要影响Java源码编译时的-encoding参数，project.reporting.outputEncoding影响报告输出。对于资源文件，Maven资源和编译插件在处理复制过滤时，也会优先读取这个属性作为默认字符集。

如果项目里使用maven-resources-plugin做资源过滤，比如把properties里的@version@替换成版本号，需要确保插件使用的编码是UTF-8：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <configuration> <encoding>UTF-8</encoding> </configuration> </plugin>

这里特别提醒：不要只设project.build.sourceEncoding，资源插件编码也要一并确认。我有一次就是只加了sourceEncoding，properties文件里的中文在本地正常，但发版到测试环境后出现了小范围乱码，最后发现是资源过滤插件把文件重新处理过一次。

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.encoding=UTF-8 -Duser.language=zh -Duser.country=CN -jar app.jar

生产环境的Linux服务器，可以先检查：

echo $LANG locale

如果输出不是UTF-8相关，需要修改环境变量，或者在启动脚本里临时设置：

export LANG=zh_CN.UTF-8 export LC_ALL=zh_CN.UTF-8

JDK 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" "%i"

macOS或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.yml，YAML文件不存在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-8

Spring的@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.encoding=UTF-8。如果file显示文件是GBK或ISO-8859-1，说明Maven/Gradle打包阶段已经把文件改坏了，回到第2章去检查资源插件编码。

5.2 Docker容器里的中文乱码

Docker部署SpringBoot时，容器基础镜像如果比较精简，可能没有安装中文字符集，Java进程即使读出正确的中文，写到控制台或者日志里也可能变成问号。

推荐在Dockerfile里显式设置：

ENV LANG=C.UTF-8 ENV JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"

JAVA_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 LANG=zh_CN.UTF-8

但不建议为了输出中文特意去装中文字符集，纯UTF-8环境已经够用。关键是保持全链路UTF-8一致。

5.3 快速确认到底是存储乱码还是显示乱码

有时程序读到的字符串是对的，只是控制台显示乱码，这种最容易被误判。区分方法很简单：把字符串写入日志文件，再用支持UTF-8的编辑器打开。

• 如果日志文件里中文正常，说明是控制台显示端问题。Windows的CMD默认GBK，IDEA的Console可能也受了系统默认编码影响。
• 如果日志文件里已经是乱码，那就是读取/转换阶段出了问题，需要继续查配置文件编码和JVM编码。

在IDEA里，可以在启动配置的VM options加-Dfile.encoding=UTF-8并设置Run -> Edit Configurations -> Environment variables里的LANG=zh_CN.UTF-8，或者直接设置Help -> Edit Custom VM Options，在idea.vmoptions里增加-Dfile.encoding=UTF-8，这能改善开发机控制台输出。

5.4 不要把HTTP请求参数乱码混进来

SpringBoot项目里还有一类常见乱码是前端请求参数乱码，比如POST表单里提交中文，后端收到后是乱码。这和properties文件乱码是两回事。

请求参数乱码通常靠Spring Boot的编码过滤器解决：

server.servlet.encoding.charset=UTF-8 server.servlet.encoding.enabled=true server.servlet.encoding.force=true

老一点的SpringBoot用：

spring.http.encoding.charset=UTF-8 spring.http.encoding.enabled=true spring.http.encoding.force=true

排查时如果发现自己明明改了properties编码，结果还是乱码，先确认问题到底出在“读取配置”还是“接收请求”。两者混在一起查会非常浪费时间，我在项目里见过的编码事故，至少有一半是因为定位错对象。

6. 常见问题与避坑清单

6.1 问题速查表

下面这张表整理了几种典型场景、可能原因和处理办法，可以直接截图放到团队知识库里：

6.2 一个容易忽略的坑：properties文件里写中文注释

很多人只注意配置值，却忽略properties文件里的中文注释。虽然注释不影响运行，但一旦构建工具把文件从GBK转成UTF-8，注释里的中文可能被转成非法字节，某些极端情况下会导致Properties.load解析失败，整个文件读不出来。

我有一次就踩过这个坑：一个老的properties文件里全是中文注释，开发机是Windows，Maven构建时资源插件用了GBK过滤，结果打包到Linux后，文件开头出现了一个非法字符，SpringBoot启动时报Malformed \uxxxx encoding。看起来和中文乱码无关，实际上是编码转换惹的祸。

所以统一编码时，不光要关注键值对，还要把注释一并处理。最简单的方式是：中文注释要么也转成Unicode转义，要么干脆换成英文。维护成本低，还能避免很多潜在问题。

6.3 用CI流水线从源头拦截乱码

团队里人多的时候，单靠某个开发者的IDE设置并不可靠。我们可以在CI流程里加一条简单检查：扫描代码仓库里的properties文件，如果存在未转义的非ASCII字符，就提示构建失败或警告。

以Linux环境为例，可以用下面的命令快速找出包含裸中文的properties文件：

grep -rlP '[^\x00-\x7F]' --include='*.properties' .

再用file命令确认这些文件的编码是否真是UTF-8：

find . -name "*.properties" -exec file -bi {} \; | grep -v 'utf-8' | head

如果项目决定全面使用“所有properties纯ASCII”的策略，那只要CI里发现非ASCII字符就报警，让人改成Unicode转义或改用YAML。这个检查成本很低，一劳永逸，很适合持续维护的项目。

还可以配合.gitattributes设置properties文件的语言，让Git在合并冲突时尽量不产生编码层面的乱跳：

*.properties text eol=lf

这些都属于工程规范层面的“防患于未然”。说实话，中文乱码技术含量不高，但重复出现很耗人精神，提前用流程堵住是最聪明的做法。

结尾前的一点经验

处理这类乱码多了之后，我最大的体会是：不要迷信“某一个配置项能一劳永逸”。编码问题本质上是一条链路，源文件编码、构建编码、运行编码三个环节必须都对齐才真正可靠。如果时间特别紧，优先用@PropertySource(encoding = "UTF-8")快速止血；如果项目还在早期，尽量用YAML替代properties；如果团队规模大，建议直接把properties统一转成Unicode转义，并在CI里加检查。

最后再分享一个小技巧：排查乱码时，先把文件用xxd或hexdump看字节，再对照实际输出，立刻能判断是存错了还是读错了。脚本写多了之后，你会发现80%的乱码问题在20秒内就能定位到根因，剩下的不过是按上面这些方案逐项修正而已。