问题根源：字符编码不一致

乱码的核心原因是：程序内部使用的字符编码 与 操作系统/文件系统实际存储的字符编码 不匹配。

1. Java 内部编码：Java 程序（字符串 String 对象）在内存中统一使用 UTF-16 编码，这是 Java 的设计原则，保证了跨平台的一致性。

2. Linux 系统默认编码：Linux 系统本身没有一个全局的“默认编码”，而是通过环境变量 LANG 或 LC_ALL 来定义，这个编码决定了：

   • 终端（Terminal）显示和输入文本的编码。
   • 大部分应用程序（包括 Java）在与文件系统交互时，如果没有特别指定，会尝试使用这个编码来处理文件名。

最常见的乱码场景：

• 场景一（开发环境常见）：你的 Linux 系统环境变量被设置为了 GBK 或 GB2312（比如为了在终端支持中文），而你的 Java 源代码文件、项目配置或服务器部署环境都使用 UTF-8，当 Java 程序使用 GBK 编码去读取一个 UTF-8 编码的文件名时，就会得到一堆乱码。
• 场景二（文件来源不同）：文件名是在 Windows 系统下创建的，Windows 默认使用 GBK 编码，这个文件被上传或复制到了一个默认使用 UTF-8 编码的 Linux 服务器上，Java 程序在 Linux 上用 UTF-8 去读取这个 GBK 编码的文件名，自然就会乱码。

如何排查和确认乱码原因？

在解决问题之前,必须先确定问题所在，你可以按照以下步骤进行排查：

检查 Linux 系统的默认编码

在终端中执行以下命令之一：

# 查看所有本地化设置
locale
# 或者只查看 LANG
echo $LANG

• 如果输出是 en_US.UTF-8 或 zh_CN.UTF-8 等，说明系统默认使用 UTF-8 编码。
• 如果输出是 zh_CN.GBK 或 zh_CN.GB2312，说明系统默认使用 GBK 编码。 这是最可能导致乱码的元凶之一。

检查 Java 程序运行时的默认编码

Java 程序可能会受到系统环境的影响，但也可以有自己的设置，可以通过以下方式检查 Java 在运行时使用的默认字符集：

在 Java 代码中打印

import java.nio.charset.Charset;
public class CheckEncoding {
    public static void main(String[] args) {
        System.out.println("Default Charset: " + Charset.defaultCharset());
        System.out.println("Default file.encoding: " + System.getProperty("file.encoding"));
    }
}

运行这个程序,观察输出结果。Charset.defaultCharset() 输出的是 GBK，而你的期望是 UTF-8，那么问题就找到了。

通过 JVM 参数启动

当你启动 Java 程序时，可以添加 -Dfile.encoding=UTF-8 参数来强制指定编码，并观察乱码是否消失。

java -Dfile.encoding=UTF-8 -jar your_application.jar

解决方案

根据排查出的原因,选择相应的解决方案。

最佳实践（从源头解决）

确保所有环节都使用 UTF-8 编码。 这是最根本、最推荐的解决方案。

1. 设置 Linux 系统环境为 UTF-8： 编辑 ~/.bashrc 或 /etc/environment 文件，添加或修改以下行：

   # 设置为 UTF-8
   export LANG="zh_CN.UTF-8"
   export LC_ALL="zh_CN.UTF-8"

   保存后,重新登录或执行 source ~/.bashrc 使其生效，然后再次用 locale 命令确认。

2. 确保 Java 项目源代码和编译使用 UTF-8：

   • IDE (如 IntelliJ IDEA/Eclipse)：在项目设置中，将 File Encoding 全部设置为 UTF-8。
   • Maven/Gradle：在构建文件中明确指定编译编码。
     • Maven (pom.xml):

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

     • Gradle (build.gradle):

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

在 Java 代码中显式指定编码

当你无法修改系统环境或项目全局设置时,可以在代码的关键位置显式指定编码。

使用 java.nio.file API (推荐)

这是 Java 7+ 推荐的方式，提供了更强大和一致的文件操作能力。Paths 和 Files 类的许多方法都支持指定 Charset。

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
public class NioFileExample {
    public static void main(String[] args) {
        // 显式使用 UTF-8 创建 Path 对象
        Path path = Paths.get("/path/to/你的文件.txt");
        try {
            // 读取文件内容，显式指定为 UTF-8
            List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
            System.out.println(lines);
            // 写入文件内容，显式指定为 UTF-8
            Files.write(path, "新内容".getBytes(StandardCharsets.UTF_8));
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

对于传统的 java.io.File API

虽然 File 本身不处理编码，但当你通过 FileInputStream/FileOutputStream 或 FileReader/FileWriter 读写文件内容时，必须指定编码。

import java.io.*;
public class IoFileExample {
    public static void main(String[] args) {
        File file = new File("/path/to/你的文件.txt");
        try (
            // 使用 InputStreamReader 包装 FileInputStream，并指定编码
            FileInputStream fis = new FileInputStream(file);
            InputStreamReader isr = new InputStreamReader(fis, StandardCharsets.UTF_8);
            BufferedReader reader = new BufferedReader(isr)
        ) {
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

JVM 启动参数（全局修复）

如果整个应用都需要使用统一的编码,可以通过 JVM 参数来设置，而无需修改代码。

# 启动应用时添加此参数
java -Dfile.encoding=UTF-8 -jar your_app.jar

注意：这种方式有一定争议，虽然能解决问题，但它会覆盖系统默认设置，可能导致其他依赖系统默认编码的库出现问题。最佳实践仍然是修改系统环境和项目配置。

特殊情况：处理已经乱码的文件名

如果你拿到一个文件名本身就是乱码（比如从日志或数据库中读出的一堆 或 字符），并且你知道它原本的编码是 GBK，你可以尝试用以下方法进行“修复”或“解码”。

import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
public class FixFileName {
    public static void main(String[] args) {
        // 这是一个假设的从错误编码中读出的乱码字节数组
        // 假设这个字节数组是用 GBK 编码存储的，但被当作了 UTF-8 来解析
        byte[] gbkBytes = "测试文件.txt".getBytes(Charset.forName("GBK"));
        // 错误的方式：将 GBK 的字节数组用 UTF-8 解码，得到乱码字符串
        String wrongName = new String(gbkBytes, StandardCharsets.UTF_8);
        System.out.println("乱码文件名: " + wrongName); // 输出类似：涓存椤�鏂囦欢.txt
        // 正确的方式：知道它是 GBK 编码，就用 GBK 来解码
        String correctName = new String(gbkBytes, Charset.forName("GBK"));
        System.out.println("正确文件名: " + correctName); // 输出：测试文件.txt
    }
}

这个场景通常用于处理“从错误来源获取的错误数据”，而不是处理文件系统本身，文件系统上的文件名一旦乱码，通常很难在不破坏的情况下修复。

总结与最佳实践

1. 预防胜于治疗：在项目初期就统一所有环节的编码为 UTF-8，包括操作系统环境、IDE、构建工具（Maven/Gradle）和数据库。
2. 使用现代 API：优先使用 java.nio.file 包中的 Path 和 Files 类，它们能更好地处理文件路径和编码问题。
3. 显式优于隐式：在读写文件内容时，总是显式地指定 Charset（如 StandardCharsets.UTF_8），不要依赖 JVM 或系统的默认值。
4. 排查要彻底：遇到乱码，先 locale 查看系统设置，再用 Charset.defaultCharset() 查看Java环境，对症下药。
5. JVM 参数是最后手段：-Dfile.encoding 可以应急，但不应作为常规解决方案，因为它会带来不可预测的副作用。