MySQL「無法初始化字元集」錯誤排查：多位元組字元集支援、編譯選項與定義檔路徑

錯誤訊息

MySQL connection failed: Can't initialize character set charset_name

兩大根因類別

1. 客戶端不支援該多位元組字元集

• 現象：伺服器使用 utf8mb4、gb18030 等多位元組字元集，舊版/精簡編譯客戶端缺少對應字元集支援。
• 解決：重新編譯客戶端庫：
  ./configure --with-charset=charset_name --with-extra-charsets=complex
  標準 MySQL 二進制發布已含 --with-extra-charsets=complex，支援所有多位元組字元集。

2. 簡單字元集定義檔路徑錯誤

• 現象：字元集未編入 mysqld，且客戶端預期路徑找不到 .conf/.xml 定義檔。
• 三種修正途徑：

1. 重新編譯客戶端納入該字元集。
2. 指定定義檔目錄：
   mysql --character-sets-dir=/usr/local/mysql/share/charsets
   或程式碼中 mysql_options(&mysql, MYSQL_SET_CHARSET_DIR, "/path")。
3. 複製定義檔至客戶端預期路徑（通常為 $MYSQL_BASE/share/charsets 或 /usr/share/mysql/charsets）。

快速診斷步驟

1. 確認伺服器支援字元集：
   SHOW CHARACTER SET LIKE 'charset_name';
2. 確認客戶端編譯支援：
   mysql --help | grep -A1 'character-sets-dir'
3. 檢查定義檔存在性：
   ls -l /usr/share/mysql/charsets/Index.xml
4. 環境變數覆蓋測試：
   export MYSQL_CHARSET_DIR=/custom/path

現代版本最佳實踐

• 統一使用 utf8mb4（MySQL 5.5.3+），涵蓋所有 Unicode 字元，含 Emoji。
• 連線字串顯式指定：
  jdbc:mysql://host/db?characterEncoding=utf8mb4&connectionCollation=utf8mb4_unicode_ci
• 避免依賴系統預設字元集，所有層級（伺服器/資料庫/表/欄位/連線）顯式宣告。

結語

字元集初始化失敗多為客戶端庫編譯缺失或定義檔路徑不匹配。標準化部署：使用官方完整二進制包、統一 utf8mb4、顯式指定連線字元集、將 character-sets-dir 納入配置管理，即可杜絕此類問題。