MySQL JDBC 中文亂碼終極解決方案：URL 參數 vs 服務端配置，驅動版本陷阱全解析

MySQL 中文亂碼的兩大流派：客戶端轉碼 vs 服務端字符集

MySQL 與 Java 應用交互時，字符集轉換發生在「JDBC 驅動」層。歷史上存在兩種主流解決路徑，且受驅動版本強影響。本文徹底梳理原理、配置差異、版本陷阱與最佳實踐。

方案一：JDBC URL 顯式指定字符集 (客戶端轉碼)

jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=UTF-8

• 原理：驅動將 Java String (UTF-16) 按 characterEncoding 編碼為字節流發送給 MySQL；讀取時按同編碼解碼為 String。
• 優點：應用層配置，無需修改數據庫服務器配置，適合共享主機/無權限場景。
• 缺點：性能損耗 (雙向編解碼)；連接池/DBCP 兼容性問題 (部分池解析 URL 參數不全，導致屬性失效)。
• 適用驅動：所有版本 (Connector/J 3.0+, 5.1, 8.0)。

方案二：服務端設置 default-character-set (服務端字符集統一)

# my.cnf / my.ini [mysqld] 區段
[mysqld]
default-character-set=utf8mb4
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

# [client] 區段 (可選，影響 mysql 命令行客戶端)
[client]
default-character-set=utf8mb4

• 原理：服務端宣告默認字符集，驅動連接後自動執行 SET NAMES utf8mb4，雙方協商一致，**無需客戶端顯式轉碼**。
• 優點：性能最優 (無額外編解碼)；全局生效，避免應用配置遺漏；支持 utf8mb4 (完整 Unicode 包含 Emoji)。
• 缺點：需服務器管理員權限修改配置並重啟；影響同實例所有連接。
• 關鍵驅動版本陷阱：
  • Connector/J 3.0.11-stable：不支持 服務端 utf8mb4，會拋出 StringIndexOutOfBoundsException: String index out of range: 40 (內部解析字符集名稱長度硬編碼 Bug)。
  • Connector/J 3.1.2-alpha / 3.1.3-beta+：修復該 Bug，**完美支持** 方案二。
  • 5.1 / 8.0 系列：完全支持，且默認自動檢測服務端字符集。

版本選擇與配置矩陣

DBCP / 連接池場景的特殊處理

若使用 Commons DBCP、Tomcat JDBC Pool、HikariCP 等，URL 參數解析可能不完整。標準做法：使用 connectionProperties 或 dataSourceProperties 顯式設置屬性。

HikariCP 示例 (推薦現代標準)

HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:mysql://localhost:3306/your_db"); // 基礎 URL 無參數
config.setUsername("user");
config.setPassword("pwd");
// 關鍵：通過 dataSourceProperties 傳遞驅動屬性
config.addDataSourceProperty("characterEncoding", "utf8mb4");
config.addDataSourceProperty("useUnicode", "true");
config.addDataSourceProperty("useSSL", "false");
config.addDataSourceProperty("serverTimezone", "Asia/Shanghai");
config.addDataSourceProperty("allowPublicKeyRetrieval", "true");

HikariDataSource ds = new HikariDataSource(config);

Tomcat JNDI DataSource (context.xml)

<Resource name="jdbc/MyDB"
          auth="Container"
          type="javax.sql.DataSource"
          driverClassName="com.mysql.cj.jdbc.Driver"
          url="jdbc:mysql://localhost:3306/your_db"
          username="user"
          password="pwd"
          connectionProperties="characterEncoding=utf8mb4;useUnicode=true;useSSL=false;serverTimezone=Asia/Shanghai"
          />

驗證字符集生效的 SQL

-- 連接後執行，確認關鍵變量
SHOW VARIABLES LIKE 'character_set_%';
SHOW VARIABLES LIKE 'collation_%';

-- 期望輸出 (方案二 utf8mb4)
character_set_client     utf8mb4
character_set_connection utf8mb4
character_set_results    utf8mb4
character_set_server     utf8mb4
collation_connection     utf8mb4_unicode_ci
collation_server         utf8mb4_unicode_ci

總結：黃金法則

1. 升級驅動：強制使用 MySQL Connector/J 5.1.49+ 或 8.0.28+，棄用 3.x 古董版。
2. 服務端統一 utf8mb4：修改 my.cnf [mysqld] 設置 default-character-set=utf8mb4，重啟 MySQL。**這是根治之道**。
3. 應用層無需額外 URL 參數 (新驅動自動協商)；若使用連接池，通過 connectionProperties 顯式傳遞 characterEncoding=utf8mb4。
4. 表/列級別同步：ALTER TABLE t CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; 確保存儲層一致。
5. JSP/HTML 頁面聲明：<%@ page contentType="text/html;charset=UTF-8" %> / <meta charset="UTF-8">。

遵循以上法則，徹底告別「????」、「」、「錯位亂碼」等 MySQL 中文噩夢。