如何解决通过JPQL向nvarchar2列插入Unicode字符乱码问题？

这个问题我之前帮好几个开发者排查过，核心原因基本都是编码链路的某个环节没配置到位，导致非拉丁字符在插入时被错误转码。咱们一步步来搞定：

1. 检查JDBC连接URL的Unicode配置 #

Oracle的JDBC驱动默认可能不会把普通字符串和NVARCHAR2列做绑定，需要显式指定参数让驱动优先处理Unicode数据。修改你的JDBC连接URL，加上这两个关键参数：

jdbc:oracle:thin:@//localhost:1521/ORCLCDB?oracle.jdbc.defaultNChar=true&charset=UTF-8

• oracle.jdbc.defaultNChar=true：让驱动默认将所有字符串参数当作NCHAR/NVARCHAR2类型处理，避免编码转换丢失
• charset=UTF-8：强制连接使用UTF-8编码传输数据

2. 用参数绑定代替JPQL硬编码字符串 #

绝对不要直接把非拉丁字符拼进JPQL语句里！比如这种写法是踩坑重灾区：

// 错误示例：硬编码中文会导致编码解析错误
em.createQuery("INSERT INTO User(name) VALUES('张三')").executeUpdate();

正确的做法是用参数绑定，让JDBC驱动直接传递Unicode数据：

// 正确示例：参数绑定避免编码转换问题
String jpql = "INSERT INTO User(name) VALUES(:username)";
em.createQuery(jpql)
  .setParameter("username", "张三")
  .executeUpdate();

参数绑定是最可靠的传递Unicode字符的方式，能绕过中间所有可能的编码解析错误。

3. 验证数据库列的字符集配置 #

虽然你说列是NVARCHAR2，但还是要确认它的字符集是Oracle推荐的AL32UTF8（完整支持Unicode）。执行以下SQL查询验证：

SELECT column_name, char_set_name 
FROM user_tab_columns 
WHERE table_name = 'YOUR_TABLE_NAME' AND column_name = 'YOUR_COLUMN_NAME';

如果返回的char_set_name不是AL32UTF8，可以修改列的字符集（记得先备份数据）：

ALTER TABLE YOUR_TABLE_NAME MODIFY YOUR_COLUMN_NAME NVARCHAR2(200) CHARSET AL32UTF8;

4. 配置JPA提供者的编码参数 #

如果你用Hibernate这类JPA实现，需要在配置文件里明确指定编码：

• 对于persistence.xml：

<property name="hibernate.connection.characterEncoding" value="UTF-8"/>
<property name="hibernate.connection.useUnicode" value="true"/>

• 对于Spring Boot的application.properties：

spring.jpa.properties.hibernate.connection.characterEncoding=UTF-8
spring.jpa.properties.hibernate.connection.useUnicode=true

5. 确认JVM默认编码 #

有时候JVM的默认编码不是UTF-8，会导致字符串在传递给JDBC驱动前就被转码。可以先打印当前JVM编码：

System.out.println("JVM默认编码：" + System.getProperty("file.encoding"));

如果输出不是UTF-8，在启动JVM时加上参数：

-Dfile.encoding=UTF-8

按这个顺序排查，一般前两步就能解决问题。核心就是确保从JVM、JDBC连接、参数传递到数据库列的整个链路都统一使用UTF-8/Unicode编码，避免中间环节的字符丢失。

内容的提问来源于stack exchange，提问作者Justin Holze