1. 问题背景与现象描述

最近在升级到JDK 25和最新版IntelliJ IDEA后，不少开发者遇到了控制台输出中文显示为乱码的问题。这个问题看似简单，但实际上涉及到JDK、IDE、操作系统和项目配置多个层面的字符编码设置。作为一名长期使用Java生态的开发者，我最近也踩了这个坑，经过一番排查和测试，总结出了一套完整的解决方案。

控制台中文乱码通常表现为以下几种形式：

• 中文字符显示为问号"???"
• 中文字符显示为方框"□□□"
• 中文字符显示为乱码符号如"所有"

这个问题在Windows系统上尤为常见，因为Windows默认使用GBK编码，而现代Java项目通常使用UTF-8编码。当JDK 25与IDEA的最新版本结合时，由于两者对字符编码处理的改进，原有的兼容性设置可能不再适用。

2. 乱码问题的根源分析

2.1 JDK层面的编码处理

JDK 25在字符编码处理上有几个重要变化：

1. 默认文件编码现在严格遵循JEP 400，优先使用UTF-8
2. 控制台编码不再自动继承系统默认编码
3. 对Windows系统的编码探测逻辑有所调整

可以通过以下命令验证JDK的默认编码：

java -XshowSettings:properties -version

在输出中查找"file.encoding"属性，JDK 25通常会显示为UTF-8。

2.2 IDEA的控制台编码机制

IntelliJ IDEA 2023.x及以后版本对控制台编码的处理也发生了变化：

1. 内置终端现在有独立的编码设置
2. 运行配置中的编码设置优先级调整
3. 对Gradle/Maven构建输出的编码处理更严格

2.3 系统环境的编码影响

Windows系统的默认编码问题不容忽视：

• 中文Windows默认使用GBK编码
• 控制台(cmd/powershell)的默认编码是GBK
• 系统区域设置可能影响Java应用的编码行为

3. 全面解决方案

3.1 修改IDEA全局设置

1. 打开File → Settings → Editor → File Encodings
2. 确保以下设置：
   • Global Encoding: UTF-8
   • Project Encoding: UTF-8
   • Default encoding for properties files: UTF-8 (勾选"Transparent native-to-ascii conversion")
3. 在Settings → Tools → Terminal中，将编码设置为UTF-8

3.2 配置运行参数

对于每个运行配置，需要添加JVM参数：

-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

可以通过以下方式设置：

1. 打开Run/Debug Configurations
2. 在对应配置的VM options中添加上述参数
3. 对于Tomcat等服务器配置，需要在对应的VM options中添加

3.3 修改Gradle/Maven配置

对于Gradle项目，在gradle.properties中添加：

org.gradle.jvmargs=-Dfile.encoding=UTF-8

对于Maven项目，在pom.xml的properties部分添加：

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

3.4 系统环境变量设置

在Windows系统中添加系统环境变量：

1. 新建系统变量JAVA_TOOL_OPTIONS，值为：

   -Dfile.encoding=UTF-8

2. 确保没有冲突的环境变量如JAVA_OPTS设置了不同的编码

3.5 针对控制台的特别设置

对于内置终端乱码问题，可以尝试：

1. 在IDEA的Help → Edit Custom VM Options中添加：

   -Dconsole.encoding=UTF-8

2. 如果使用外部终端，确保终端的编码设置为UTF-8：
   • 对于cmd：执行chcp 65001
   • 对于PowerShell：执行[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

4. 验证与测试方案

4.1 创建测试用例

编写简单的测试类：

public class EncodingTest { public static void main(String[] args) { System.out.println("中文测试"); System.out.println("当前文件编码：" + System.getProperty("file.encoding")); System.out.println("控制台编码：" + System.getProperty("console.encoding")); } }

4.2 预期结果

正确的输出应该显示：

中文测试 当前文件编码：UTF-8 控制台编码：UTF-8

4.3 常见问题排查

如果仍然出现乱码，可以按以下步骤排查：

1. 检查IDEA运行配置中的VM options是否生效
2. 确认gradle.properties或pom.xml中的设置是否正确加载
3. 尝试在代码中显式设置编码：

   PrintStream out = new PrintStream(System.out, true, "UTF-8"); out.println("强制UTF-8输出测试");

4. 检查系统环境变量是否有冲突

5. 高级配置与优化

5.1 针对不同场景的配置

1. 单元测试配置：

   • 在Run → Edit Configurations → Templates → JUnit中设置默认VM options
   • 确保测试资源文件也是UTF-8编码

2. Spring Boot项目：

   • 在application.properties或application.yml中明确设置：

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

3. Web项目：

   • 在web.xml中添加：

     <filter> <filter-name>encodingFilter</filter-name> <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class> <init-param> <param-name>encoding</param-name> <param-value>UTF-8</param-value> </init-param> <init-param> <param-name>forceEncoding</param-name> <param-value>true</param-value> </init-param> </filter>

5.2 日志输出编码设置

对于Logback/Log4j等日志框架，需要确保编码设置：

<!-- Logback配置示例 --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <charset>UTF-8</charset> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender>

5.3 多模块项目的统一配置

对于大型多模块项目，建议：

1. 在父pom中定义统一的编码属性
2. 使用Maven插件确保资源文件编码：

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

3. 在根目录的gradle.properties中设置全局编码

6. 常见问题与解决方案

6.1 问题1：设置后仍然部分乱码

可能原因：

• 某些第三方库强制设置了编码
• 系统环境变量被覆盖
• 终端模拟器自身编码问题

解决方案：

1. 使用以下代码检查实际生效的编码：

   System.out.println("实际文件编码：" + System.getProperty("file.encoding"));

2. 检查是否有代码调用了System.setProperty("file.encoding", "GBK")
3. 尝试使用不同的终端(如Windows Terminal替代cmd)

6.2 问题2：Gradle构建输出乱码

解决方案：

1. 在gradle-wrapper.properties中添加：

   org.gradle.jvmargs=-Dfile.encoding=UTF-8

2. 在build.gradle中添加：

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

6.3 问题3：测试用例中的中文断言失败

解决方案：

1. 确保测试文件本身是UTF-8编码
2. 在测试类中添加：

   @BeforeAll static void setup() { System.setProperty("file.encoding", "UTF-8"); }

3. 对于JUnit 5，可以在src/test/resources下创建junit-platform.properties：

   junit.jupiter.execution.parallel.enabled=true file.encoding=UTF-8

7. 长期解决方案与最佳实践

1. 统一团队开发环境：

   • 在项目文档中明确要求所有开发者使用UTF-8编码
   • 在.gitattributes中添加：

     *.java text eol=lf charset=utf-8 *.properties text eol=lf charset=utf-8

   • 在IDE配置文件中统一编码设置

2. CI/CD环境配置：

   • 在Jenkins/GitHub Actions等CI工具中明确设置编码环境变量
   • 对于Docker构建，在Dockerfile中添加：

     ENV LANG C.UTF-8 ENV LC_ALL C.UTF-8

3. 项目模板化：

   • 创建项目模板时包含正确的编码配置
   • 使用Archetype或Gradle Init模板预设UTF-8配置

4. 监控与报警：

   • 在代码审查中加入编码检查
   • 使用SonarQube等工具检测潜在的编码问题

在实际项目中，我发现最可靠的解决方案是"全方位防御"策略：即在操作系统、IDE、构建工具、运行环境和代码层面都进行UTF-8的强制设置。虽然看起来有些冗余，但这能确保在各种环境下都能正确显示中文。特别是在团队协作和持续集成环境中，这种全方位的配置可以避免因环境差异导致的问题。