【Oracle 填坑日记】“ZHS16GBK 字符集”→“缺失 gdk_custom.jar”连环坑：一次 Maven 依赖的蝴蝶效应

作者：@Neoest
时间：2025-08-15
关键词：Oracle、ZHS16GBK、orai18n.jar、gdk_custom.jar、Maven、class-path

---

1. 问题现场

刚刚因为一些原因导致程序必须由mysql切换至oracle，在信心十足的导入oracle驱动包+替换了jdbc的四大配置之后没有验证直接灰度发布，系统启动后访问页面一直不停的刷错：

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

老司机一看就知道缺 orai18n.jar，于是 顺手 在 pom.xml 补了一刀：

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

重启，以为万事大吉，结果新异常呼啸而来：

Caused by: java.nio.file.NoSuchFileException: ...\orai18n\21.9.0.0\gdk_custom.jar

注意：gdk_custom.jar 并不在 Maven Central！
整个依赖树只有 orai18n-21.9.0.0.jar，而 Oracle 官方把 NLS 资源进一步拆成了多份 jar，Maven 版本并未同步发布完整包。

---

2. 根因复盘

阶段	现象	原因
1️⃣ 启动失败	ZHS16GBK 字符集找不到	JDBC 驱动需要 orai18n.jar
2️⃣ 补依赖	引入 orai18n Maven 坐标	该坐标只含 核心 NLS 代码，不包含 gdk_custom.jar 等资源
3️⃣ 再启动	NoSuchFileException: gdk_custom.jar	驱动在运行时 反射加载 gdk_custom.jar，Maven 仓库缺文件

---

3. 解决方案

✅ 方案 A：使用 完整版 Oracle JDBC 驱动（推荐）

1. 去 Oracle 官网 下载 ojdbc8/ojdbc11 + orai18n + ons + ucp 的 完整 zip。
2. 将下列文件 手动 install 到本地仓库或私服：

mvn install:install-file \
  -Dfile=orai18n.jar \
  -DgroupId=com.oracle.database.nls \
  -DartifactId=orai18n-complete \
  -Dversion=21.9.0.0 \
  -Dpackaging=jar

3. pom.xml 改为引用 完整版：

<!-- 完整 NLS 支持 -->
<dependency>
    <groupId>com.oracle.database.nls</groupId>
    <artifactId>orai18n-complete</artifactId>
    <version>21.9.0.0</version>
</dependency>

注意：官方 Maven 坐标没有 gdk_custom.jar，必须手动上传。

---

✅ 方案 B：改用 瘦驱动 + 服务器端字符集（无需 NLS jar）

如果数据库字符集是 AL32UTF8，在连接串里 强制客户端字符集：

jdbc:oracle:thin:@//dbhost:1521/orclpdb?oracle.net.CONNECT_TIMEOUT=3000&oracle.jdbc.defaultNChar=true

并加 JVM 参数：

-Doracle.jdbc.defaultNChar=true
-Doracle.jdbc.convertNcharLiterals=true

即可绕过 ZHS16GBK，无需任何 NLS jar。

---

✅ 方案 C：Spring Boot 多仓库配置（企业私服）

<!-- 私服上已上传完整 orai18n-complete -->
<repositories>
    <repository>
        <id>nexus-releases</id>
        <url>https://nexus.xxx.com/repository/maven-releases/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.oracle.database.nls</groupId>
    <artifactId>orai18n-complete</artifactId>
    <version>21.9.0.0</version>
</dependency>

CI/CD 全程无人工干预。

---

4. 小结

方案	场景	步骤	备注
手动安装完整 orai18n	任何环境	3 步	官方推荐
瘦驱动 + UTF8	新建库/可改字符集	2 步	无需额外 jar
私服统一	企业内网	1 步	零侵入

---

5. 一键复制版补丁

只想快速修完跑路：

# 1. 下载官方完整 jdbc 包
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211000/ojdbc11-full.tar.gz

# 2. 安装 orai18n-complete
mvn install:install-file \
  -Dfile=orai18n.jar \
  -DgroupId=com.oracle.database.nls \
  -DartifactId=orai18n-complete \
  -Dversion=21.9.0.0 \
  -Dpackaging=jar

<!-- 3. pom 引用 -->
<dependency>
    <groupId>com.oracle.database.nls</groupId>
    <artifactId>orai18n-complete</artifactId>
    <version>21.9.0.0</version>
</dependency>

---

6. 参考资料

• Oracle JDBC 21c 官方文档：NLS 支持
• Maven Central 缺失 orai18n 资源文件说明

如果本文帮到你，记得点赞收藏！评论区一起交流更多 Oracle JDBC 坑位～