SpringBoot中properties文件中文乱码的5种解决方案-代码聚汇网

SpringBoot中properties文件中文乱码的5种解决方案

哗啦啦的小流弊

1. 问题背景与现象分析

在SpringBoot项目开发过程中，properties文件作为常用的配置存储方式，经常会出现中文内容显示为乱码的情况。这个问题看似简单，却困扰着不少开发者。我自己在早期项目中也多次踩坑，明明在IDE里显示正常的中文，运行时却变成了一堆问号或奇怪的符号。

乱码问题的本质是字符编码不一致导致的。当Java程序读取properties文件时，如果使用的编码方式与文件实际编码不匹配，就会发生这种转换错误。常见的乱码表现形式包括：

中文字符显示为"???"
出现"å®å¨"这类乱码组合
控制台输出为方块符号

2. 乱码产生的根本原因

2.1 文件编码与读取编码不匹配

properties文件默认应该使用ISO-8859-1编码保存，但现代IDE通常默认使用UTF-8。这种编码差异是乱码的主因。当SpringBoot的PropertySourceLoader加载文件时，如果没有明确指定编码，就会使用平台默认编码（可能是GBK或UTF-8）读取ISO-8859-1格式的文件。

2.2 IDE与运行环境编码差异

开发时IDE（如IntelliJ IDEA）可能自动将properties文件保存为UTF-8，而Maven/Gradle构建时又没有正确处理编码转换，导致最终打包的应用读取了错误编码的文件。

2.3 SpringBoot默认处理机制

SpringBoot的ConfigFileApplicationListener在加载application.properties时，底层使用的是PropertiesPropertySourceLoader，它继承Java原生的Properties类，而这个类默认使用ISO-8859-1编码读取文件。

3. 五种解决方案及实现细节

3.1 方案一：统一文件编码为UTF-8

步骤：

在IDE中设置properties文件编码：
- IntelliJ IDEA：Settings → Editor → File Encodings
- 将"Default encoding for properties files"改为UTF-8
- 勾选"Transparent native-to-ascii conversion"
在pom.xml中配置Maven过滤：

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

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>**/*.properties</include>
            </includes>
        </resource>
    </resources>
</build>

原理：
通过统一编码设置，确保从编辑到构建的整个流程都使用UTF-8编码处理文件。

3.2 方案二：使用Unicode转义序列

将中文转换为Unicode编码形式：

code复制welcome.message=\u4F60\u597D\uFF0C\u6B22\u8FCE\u4F7F\u7528

转换工具：

使用JDK自带的native2ascii工具：

bash复制native2ascii -encoding UTF-8 input.properties output.properties

在线转换工具（注意安全性）

适用场景：
需要严格兼容各种环境的传统项目，或者必须使用ISO-8859-1编码的情况。

3.3 方案三：自定义PropertySourceLoader

创建自定义的UTF-8PropertiesPropertySourceLoader：

java复制public class UTF8PropertiesPropertySourceLoader implements PropertySourceLoader {
    @Override
    public String[] getFileExtensions() {
        return new String[]{"properties"};
    }

    @Override
    public List<PropertySource<?>> load(String name, Resource resource) 
        throws IOException {
        Properties properties = new Properties();
        try (InputStreamReader reader = new InputStreamReader(
            resource.getInputStream(), StandardCharsets.UTF_8)) {
            properties.load(reader);
        }
        return Collections.singletonList(
            new PropertiesPropertySource(name, properties));
    }
}

然后在META-INF/spring.factories中注册：

code复制org.springframework.boot.env.PropertySourceLoader=\
com.example.UTF8PropertiesPropertySourceLoader

3.4 方案四：使用YAML替代Properties

YAML原生支持UTF-8编码，可以完美解决中文乱码问题：

yaml复制welcome: 
  message: "你好，欢迎使用"

转换注意事项：

需要添加snakeyaml依赖
键名中不能使用点号(.)，需要用层级结构替代
数组和复杂结构表达更清晰

3.5 方案五：运行时编码指定

在启动参数中强制指定编码：

bash复制java -Dfile.encoding=UTF-8 -jar your-app.jar

或在application.properties中配置：

code复制spring.config.encoding=UTF-8

4. 方案对比与选型建议

方案	优点	缺点	适用场景
统一UTF-8编码	一劳永逸，无需代码改动	需要团队统一配置	新项目，团队可控环境
Unicode转义	兼容性最好	可读性差，维护困难	必须使用ISO-8859-1的老系统
自定义Loader	灵活控制读取逻辑	增加维护成本	需要特殊处理的复杂场景
转用YAML	功能强大，格式清晰	学习成本，兼容性问题	新项目，配置复杂的情况
运行时指定	简单快速	依赖运行环境	临时解决方案

个人建议：

新项目优先考虑YAML或统一UTF-8编码方案
老系统维护可使用Unicode转义
特殊需求场景采用自定义Loader

5. 深度避坑指南

5.1 多环境下的编码陷阱

即使开发环境解决了乱码，测试和生产环境仍可能出现问题。需要检查：

服务器LANG环境变量设置
Docker基础镜像的默认编码
CI/CD流水线中的编码设置

5.2 IDE的隐形转换

某些IDE会"智能"地转换文件编码而不提示，建议：

用十六进制工具检查文件实际编码
在版本控制中对比文件变化
禁用IDE的自动转换功能

5.3 资源过滤的副作用

Maven资源过滤可能导致编码问题：

xml复制<!-- 错误的过滤配置会导致编码转换 -->
<resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
</resource>

建议对properties文件单独配置过滤，或使用escape处理特殊字符。

5.4 第三方库的编码依赖

某些库可能强制使用特定编码读取配置，如：

MyBatis的mapper.xml文件
Logback的logback.xml
Thymeleaf模板文件

需要检查各组件文档确认其编码要求。

6. 验证与测试方法

6.1 单元测试验证

编写测试用例验证配置读取：

java复制@Test
public void testChineseProperties() {
    String message = env.getProperty("welcome.message");
    assertThat(message).isEqualTo("你好，欢迎使用");
}

6.2 运行时检查

在Controller中添加测试端点：

java复制@GetMapping("/checkEncoding")
public String checkEncoding() {
    return env.getProperty("welcome.message");
}

6.3 日志输出验证

在启动时输出配置值：

java复制@PostConstruct
public void init() {
    log.info("配置信息: {}", welcome.getMessage());
}

7. 高级场景解决方案

7.1 多字节语言支持

对于日文、韩文等多字节文字，建议：

统一使用UTF-8编码
数据库连接也设置characterEncoding=UTF-8
确保HTTP请求/响应使用UTF-8

7.2 动态配置刷新

结合Spring Cloud Config时，需要注意：

yaml复制spring:
  cloud:
    config:
      encoding: UTF-8

7.3 自定义配置文件

加载非application.properties文件时：

java复制@PropertySource(value = "classpath:custom.properties", 
    encoding = "UTF-8")
public class AppConfig {
    //...
}

8. 最佳实践总结

经过多个项目的实践验证，我总结出以下可靠方案：

项目初始化时：
- 统一IDE、构建工具和运行环境的编码设置为UTF-8
- 优先考虑使用YAML格式的配置文件
- 在.gitattributes中添加*.properties text encoding=utf-8
已有项目改造：
- 先用native2ascii转换现有配置文件
- 逐步迁移到YAML格式
- 添加编码验证测试用例
团队协作规范：
- 在项目文档中明确编码规范
- 在CI流水线中添加编码检查
- 使用pre-commit钩子验证properties文件编码

这套方案在我负责的多个企业级项目中验证有效，特别是在需要多语言支持的国际化项目中表现稳定。关键在于从开发到部署的全流程统一编码标准，而不是仅仅解决表面的读取问题。