錯誤現象

MySQL Connection Failed: Can't initialize character set charset_name

客戶端/驅動程式無法載入指定字符集的定義或轉換邏輯。

三大核心成因

1. 客戶端未編譯支援該字符集

多位元組字符集 (utf8mb4, gbk, sjis 等) 需客戶端庫編譯時包含。標準 MySQL 二進制發布已含 --with-extra-charsets=complex，但精簡版/嵌入式/第三方編譯可能缺失。

解決：重新編譯客戶端 --with-charset=charset_name 或 --with-extra-charsets=complex；或升級官方完整版客戶端庫。

2. 字符集定義檔缺失/路徑錯誤

簡單字符集 (latin1 等) 依賴 .conf/.xml 定義檔。客戶端預期路徑 (通常為 share/charsets/ 或 mysql/charsets/) 找不到檔案。

解決三選一：

1. 重新編譯指定 --with-charset=charset_name
2. 啟動參數指定目錄：--character-sets-dir=/path/to/charsets
3. 複製定義檔至客戶端預期目錄

3. 字符集名稱拼寫/大小寫錯誤

• utf8 vs utf8mb4 (MySQL 8.0 預設 utf8mb4)
• gb2312 實際為 gbk 超集
• 連線字串 charset=utf8mb4 驅動版本需支援

排查步驟清單

1. 確認伺服器支援：SHOW CHARACTER SET LIKE 'charset_name';
2. 確認客戶端編譯選項：mysql --help | grep charset 或驅動文檔
3. 檢查 character_sets_dir 變數：SHOW VARIABLES LIKE 'character_sets_dir';
4. 測試連線指定字符集：mysql --default-character-set=charset_name -u root -p
5. 檢查環境變數 LANG/LC_ALL 干擾

最佳實踐建議

• 全鏈路統一 utf8mb4：資料庫、表、欄位、連線、應用層
• 連線字串顯式指定：jdbc:mysql://host/db?characterEncoding=utf8mb4 / mysqli_set_charset($link, 'utf8mb4')
• 避免依賴預設值，配置檔 [client] default-character-set=utf8mb4
• 容器化部署掛載完整 charsets 目錄