Sign in Subscribe
idea

IntelliJ IDEA Maven 编译输出乱码问题解决方案

vacuity

• 4 min read
IntelliJ IDEA Maven 编译输出乱码问题解决方案

问题现象

在 IntelliJ IDEA 中执行 Maven 编译时，控制台输出出现乱码，显示为 ���... 等不可读字符。

[INFO] Compiling 2724 source files to /path/to/target/classes
[INFO] /path/to/SomeService.java: ���������������

问题原因

根本原因

从 IntelliJ IDEA 2025.2 版本开始，Maven 的执行方式发生了重大变化：

  1. 旧版本（2025.1 及之前）

    • 直接调用 java.exe 执行 Maven

  2. 新版本（2025.2 及之后）

    • 通过 cmd.exe /c（Windows）或 shell（macOS/Linux）来启动 Maven
    • 可以从控制台输出结果看到这个变化

编码冲突

  • Windows 系统：cmd.exe 默认使用 GBK 编码
  • 项目源码：通常使用 UTF-8 编码
  • 结果：编码不一致导致中文和特殊字符显示为乱码

为什么传统方法无效

即使你已经设置了以下配置，问题仍可能存在：

  1. IDEA 的 File Encoding 设置为 UTF-8
  2. Maven 配置中指定 -Dfile.encoding=UTF-8
  3. pom.xml 中配置了编码属性：
    <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

原因：Maven 通过 cmd/shell 启动后，JVM 可能仍未正确继承或使用 UTF-8 编码。

解决方案

方法：设置 JAVA_TOOL_OPTIONS 环境变量

通过在 IDEA 中为 Maven 设置 JAVA_TOOL_OPTIONS 环境变量，强制 JVM 使用 UTF-8 编码。

详细步骤

1. 打开 IDEA 设置

Windows/Linux:

  • 快捷键：Ctrl + Alt + S
  • 或菜单：File → Settings

macOS:

  • 快捷键：Cmd + ,
  • 或菜单：IntelliJ IDEA → Preferences

2. 导航到 Maven Runner 配置

按照以下路径进入：

Build, Execution, Deployment
  └─ Build Tools
      └─ Maven
          └─ Runner

3. 添加环境变量

找到 Environment variables 字段：

  1. 点击右侧的文件夹图标或输入框
  2. 添加新的环境变量：
    • Name: JAVA_TOOL_OPTIONS
    • Value: -Dfile.encoding=UTF-8

完整格式：

JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8

4. 应用设置

  1. 点击 Apply 按钮
  2. 点击 OK 关闭设置窗口

5. （可选）清除缓存并重启

如果问题仍存在，可以清除缓存：

  1. 菜单：File → Invalidate Caches...
  2. 勾选相关选项
  3. 点击 Invalidate and Restart

注意：大多数情况下无需重启，设置会立即生效。

验证方法

重新执行 Maven 编译命令（如 mvn compile 或 mvn clean install），检查控制台输出是否正常显示中文。

适用范围

受影响的版本

  • IntelliJ IDEA 2025.2 及更高版本

受影响的系统

  • Windows：最常见（cmd.exe 默认 GBK）
  • macOS：可能受影响
  • Linux：可能受影响（取决于系统 locale 设置）

技术原理

JAVA_TOOL_OPTIONS 环境变量

JAVA_TOOL_OPTIONS 是一个特殊的 JVM 环境变量：

  • 作用：在 JVM 启动时自动应用指定的选项
  • 优先级：高于其他配置方式
  • 生效范围：对所有通过该环境变量启动的 Java 进程有效

为什么这个方法有效

  1. IDEA 通过 shell/cmd 启动 Maven
  2. Maven 进程继承 JAVA_TOOL_OPTIONS 环境变量
  3. JVM 在启动时自动应用 -Dfile.encoding=UTF-8
  4. 所有输出使用统一的 UTF-8 编码

其他注意事项

pom.xml 中的编码配置

虽然这不是解决乱码的主要方法，但仍建议在 pom.xml 中明确指定编码：

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

这可以确保：

  • 源代码编译使用正确编码
  • 资源文件处理使用正确编码
  • 报告生成使用正确编码

全局 Maven 配置

如果需要在命令行中也使用 UTF-8，可以在 ~/.mavenrc（macOS/Linux）或环境变量中设置：

macOS/Linux:

# ~/.mavenrc
export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"

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

变量名: JAVA_TOOL_OPTIONS
变量值: -Dfile.encoding=UTF-8

相关资源

总结

IntelliJ IDEA 2025.2 版本改变了 Maven 执行方式，导致编码传递出现问题。通过在 IDEA 的 Maven Runner 配置中设置 JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 环境变量，可以强制 JVM 使用 UTF-8 编码，从而彻底解决乱码问题。

此方法简单有效，无需修改系统配置或项目代码，设置后立即生效。