什么是“不可映射字符”？

“不可映射字符” 指的是：你试图用一种编码（GBK）去表示一个字符,但该编码的字符集中根本不存在这个字符。

一个绝佳的比喻： 想象你有一个只能写汉字的笔记本（GBK 编码），现在你试图在上面写一个日文片假名 "ã"（Unicode 字符），你的笔记本里没有这个字，所以你无法写上去，这个 "ã" 就是相对于这个“GBK笔记本”的“不可映射字符”。

在计算机中：

• 字符：是抽象的符号，"A", "中", "€", "😂"，它们通常用 Unicode 编码（如 U+0041, U+4E2D）来唯一标识。
• 编码：是规则，规定了如何将一个或多个字节表示一个字符。
  • GBK：是中文编码标准，收录了大部分常用的汉字、符号，但不包含日文、韩文、欧元符号 "€"、emoji 等其他语言的字符。
  • UTF-8：是 Unicode 的一种实现方式,它几乎可以表示地球上所有的字符。

当你尝试将一个 GBK 无法表示的 Unicode 字符保存到使用 GBK 编码的文件或发送给使用 GBK 编码的系统时，就会出错，提示 "GBK 不可映射字符"。

在 Java 中如何发生？

这个错误通常发生在字节流操作中，当你明确指定了 Charset 为 GBK，但数据源中包含了 GBK 不支持的字符。

最常见的场景是 文件读写。

场景1：写入文件时发生错误

如果你从一个 String（在 Java 内部总是用 UTF-16 表示）中获取字符，然后尝试用 OutputStreamWriter 或 FileOutputStream 以 GBK 编码写入文件，而 String 中恰好包含 GBK 不支持的字符，就会抛出 CharacterCodingException。

示例代码（会抛出异常）：

import java.io.*;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
public class GbkUnmappableExample {
    public static void main(String[] args) {
        // 这个字符串包含 GBK 无法表示的字符：欧元符号 '€'
        String content = "这是一个测试，包含一个欧元符号：€";
        // 指定使用 GBK 编码写入文件
        Charset gbkCharset = Charset.forName("GBK");
        try (OutputStreamWriter writer = new OutputStreamWriter(
                new FileOutputStream("test_gbk.txt"), gbkCharset)) {
            writer.write(content);
            System.out.println("写入成功！");
        } catch (CharacterCodingException e) {
            // 这就是我们要捕获的 "GBK 不可映射字符" 异常
            System.err.println("编码错误：检测到 GBK 无法映射的字符！");
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

运行结果：

编码错误：检测到 GBK 无法映射的字符！
java.nio.charset.CharacterCodingException: Unmappable character for encoding GBK
    at java.nio.charset.CharsetEncoder.onMalformedInput(CharsetEncoder.java:1033)
    at java.nio.charset.CharsetEncoder.encode(CharsetEncoder.java:765)
    ...

场景2：读取文件时发生错误

如果你尝试读取一个用 UTF-8 编码保存的文件（里面包含 GBK 不支持的字符），但却错误地使用 GBK 编码去读取，程序会尝试将 UTF-8 的字节流“强行”解释为 GBK 字符，这通常会导致乱码,或者在遇到无法组合的字节序列时抛出异常。

如何解决？

解决这个问题的核心思想是：确保编码和解码使用的是同一种规则，并且这种规则能够覆盖你的数据。

修改编码为 UTF-8（推荐）

UTF-8 是目前事实上的标准，它能处理所有 Unicode 字符,是解决编码问题的首选。

修改后的代码（正确写入）：

import java.io.*;
import java.nio.charset.StandardCharsets;
public class Utf8Solution {
    public static void main(String[] args) {
        String content = "这是一个测试，包含一个欧元符号：€ 和一个笑脸 😂";
        // 使用 UTF-8 编码写入文件
        try (OutputStreamWriter writer = new OutputStreamWriter(
                new FileOutputStream("test_utf8.txt"), StandardCharsets.UTF_8)) {
            writer.write(content);
            System.out.println("使用 UTF-8 写入成功！");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

优点：

• 兼容性极好,可以处理任何语言的字符。
• 是 Web 开发、数据库、API 接口等领域的通用标准。

注意事项：

• 确保读取该文件时也使用 UTF-8 编码,否则会乱码。

替换或忽略不可映射字符（不推荐，但有场景）

在某些特定场景下，你可能无法修改目标系统的编码，只能“委曲求全”，这时，你可以告诉 Java 在遇到无法映射的字符时，进行替换或忽略,而不是直接报错。

这需要使用 CharsetEncoder 并配置其 onUnmappableCharacter 策略。

示例代码（替换不可映射字符）：

import java.io.*;
import java.nio.charset.Charset;
import java.nio.charset.CharsetEncoder;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
public class GbkReplacementExample {
    public static void main(String[] args) {
        String content = "测试符号：€ 和 😂";
        // 1. 创建 GBK 编码器
        Charset gbkCharset = Charset.forName("GBK");
        CharsetEncoder encoder = gbkCharset.newEncoder();
        // 2. 配置策略：遇到无法映射的字符时，用 '?' 替换
        encoder.onUnmappableCharacter(CodingErrorAction.REPLACE);
        try (OutputStreamWriter writer = new OutputStreamWriter(
                new FileOutputStream("test_gbk_replace.txt"), encoder)) {
            writer.write(content);
            System.out.println("写入成功（已替换不可映射字符）！");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

运行结果： 文件 test_gbk_replace.txt 的内容会是：

测试符号：? 和 ?

可选策略：

• CodingErrorAction.REPLACE：替换（如上例，默认替换为 ）。
• CodingErrorAction.IGNORE：直接忽略该字符。
• CodingErrorAction.report(CodingErrorAction.REPLACE)：报告错误（默认行为，即抛出异常）。

缺点：

• 数据会丢失或失真,可能导致信息不完整。
• 只应在无法控制目标编码且对数据完整性要求不高的临时处理场景下使用。

1. 优先使用 UTF-8：在所有新的 Java 项目、文件存储、网络通信、数据库连接中，默认使用 UTF-8 编码,这是避免编码问题的根本方法。
2. 明确指定编码：永远不要依赖平台的默认编码（Charset.defaultCharset()），在创建 InputStreamReader, OutputStreamWriter, String 构造函数等时，显式地传入 StandardCharsets.UTF_8 或其他你确定的编码。
3. 处理遗留系统：当你必须与一个使用 GBK/GBK2312 等旧编码的遗留系统交互时，要格外小心，在数据进入你的系统（读入）时，用该编码解码；在数据离开你的系统（写出）时，用该编码编码，并在关键代码处添加 try-catch (CharacterCodingException) 块，或者配置 CharsetEncoder 的错误处理策略。
4. 理解 byte[] 和 String 的区别：String 在 Java 内存中是 UTF-16 的，编码是 String -> byte[] 的过程，解码是 byte[] -> String 的过程,错误通常发生在编码环节。

记住这个原则：数据在内存中是 Unicode（String），在磁盘和网络上是字节流（byte[]），正确地在两者之间转换的桥梁就是编码（Charset）。