💥 解决 ORA-17056：不支持的字符集 (在类路径中添加 orai18n.jar): ZHS16GBK

在使用 Java 调用 Oracle 数据库 时，有时会遇到以下异常：

java.sql.SQLException: ORA-17056: 不支持的字符集 (在类路径中添加 orai18n.jar): ZHS16GBK

🧩 一、问题原因

Oracle 数据库支持多种字符集，比如常见的：

AL32UTF8（UTF-8）
ZHS16GBK（简体中文 GBK）
ZHT16BIG5（繁体中文 BIG5）

当数据库使用了 ZHS16GBK 这样的中文字符集时， Java 程序通过 Oracle JDBC 驱动（如 ojdbc8.jar） 访问数据库时，如果驱动中 没有包含中文字符集支持类，就会抛出这个异常。

🧠 二、核心原因

Oracle 的字符集支持被拆分到独立的国际化包中：

✅ orai18n.jar（即 Oracle Internationalization Library）

JDBC 驱动（ojdbc8.jar）默认不包含中文字符集定义，所以当数据库返回 ZHS16GBK 编码的数据时，驱动无法识别。

⚙️ 三、解决方案

解决方法非常简单： 为你的 ojdbc 版本添加匹配的 orai18n.jar 依赖。

✅ 1. 确认当前使用的 JDBC 版本

打开 pom.xml，查看 Oracle JDBC 驱动配置：

<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <version>23.2.0.0</version>
</dependency>

这里可以看到版本号是 23.2.0.0。

✅ 2. 添加对应版本的国际化包（orai18n.jar）

orai18n.jar 必须与 ojdbc 版本完全一致！

在上面的示例中，需要添加：

<dependency>
    <groupId>com.oracle.database.nls</groupId>
    <artifactId>orai18n</artifactId>
    <version>23.2.0.0</version>
</dependency>

Maven 会自动下载并加入 classpath，如果你是手动部署 jar，请确保它与应用一起打包或位于 BOOT-INF/lib/（Spring Boot 项目）中。

✅ 3. 清理并重新启动项目

执行以下命令重新构建：

mvn clean package

然后启动项目。若启动时日志中不再出现 Non supported character set: ZHS16GBK，说明问题已解决。

🧾 四、示例完整依赖配置

<dependencies>
    <!-- Oracle JDBC 驱动 -->
    <dependency>
        <groupId>com.oracle.database.jdbc</groupId>
        <artifactId>ojdbc8</artifactId>
        <version>23.2.0.0</version>
    </dependency>

    <!-- Oracle 国际化字符集支持 -->
    <dependency>
        <groupId>com.oracle.database.nls</groupId>
        <artifactId>orai18n</artifactId>
        <version>23.2.0.0</version>
    </dependency>
</dependencies>

✅ 五、适配其他版本说明

JDBC 驱动	orai18n 版本	说明
ojdbc8 19.3.0.0	orai18n 19.3.0.0	Oracle 19c 官方推荐组合
ojdbc8 21.1.0.0	orai18n 21.1.0.0	适用于 Oracle 21c
ojdbc8 23.2.0.0	orai18n 23.2.0.0	最新版本（支持 JDK17+）

🧩 六、补充：如何确认数据库字符集

如果你不确定数据库的字符集，可以在 SQL*Plus 或任何 SQL 工具中执行：

SELECT userenv('language') FROM dual;

结果示例：

AMERICAN_AMERICA.ZHS16GBK

这表示数据库使用了 ZHS16GBK 字符集。

🚀 七、总结

问题	原因	解决方案
ORA-17056: 不支持的字符集	JDBC 驱动不包含中文字符集支持	添加 `orai18n.jar`
orai18n 版本不匹配	不同版本的 JDBC 与 NLS 包不兼容	版本号必须一致
JAR 未被加载	未打包进 classpath	确保位于运行时 classpath 或 `BOOT-INF/lib`

💡 参考链接

✅ 总结一句话：

出现 “不支持的字符集：ZHS16GBK” 的根本原因，是 缺少或版本不匹配的 orai18n.jar。只要为你的 ojdbc8 添加匹配版本的 orai18n 依赖，即可完美解决。

解决 ORA-17056：不支持的字符集 (在类路径中添加 orai18n.jar): ZHS16GBK