MySQL 存儲 Emoji 表情報錯？根因與徹底解決方案（utf8mb4 遷移指南）

MySQL 存儲 Emoji 表情報錯？根因與徹底解決方案（utf8mb4 遷移指南）

線上業務抓取微博數據入庫時，頻繁拋出 java.sql.SQLException: Incorrect string value: '\xF0\x9F\x92\xAA'... 異常，導致數據寫入失敗。本文深度解析字符集編碼根因，給出生產環境平滑遷移至 utf8mb4 的完整方案。

一、 現象還原與錯誤分析

異常堆棧

java.sql.SQLException: Incorrect string value: '\xF0\x9F\x92\xAA' for column 'raw_json' at row 1
org.springframework.jdbc.UncategorizedSQLException: ...

raw_json 字段包含 Emoji 字符（如 💪），十六進制 \xF0\x9F\x92\xAA 佔用 4 字節。

根因：MySQL 「utf8」是偽 utf-8

• MySQL 早期實現的 utf8（實為 utf8mb3）最多僅支持 3 字節字符，覆蓋基本多文種平面（BMP）。
• Emoji、生僻漢字屬於輔助平面，需 4 字節編碼，超出 utf8 範圍，導致寫入截斷報錯。
• 真正的 UTF-8 在 MySQL 中對應字符集 utf8mb4（mb4 = most bytes 4）。

二、 生產環境遷移方案（零停機/低風險）

原則：先測試環境驗證，避開業務高峰，申請停機窗口操作。

步驟 1：修改實例級配置

編輯 my.cnf（或 my.ini），[mysqld] 區塊新增/修改：

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init_connect = 'SET NAMES utf8mb4'

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

重啟 MySQL 服務生效。

步驟 2：修改庫、表、欄位字符集

pt-online-schema-change 或 gh-ost 在線變更。


步驟 3：驗證應用端連線配置

JDBC URL 追加參數：?characterEncoding=utf8mb4&connectionCollation=utf8mb4_unicode_ci
連接池（HikariCP/Druid）初始化 SQL 執行 SET NAMES utf8mb4。


步驟 4：全鏈路壓測驗證
測試環境模擬寫入含 Emoji 的 JSON、文本，確認無異常；檢查讀取、檢索、備份還原流程正常。

三、 避坑指南與最佳實踐

新建專案直接指定 utf8mb4，不要再用 utf8。
索引長度限制：utf8mb4 單字符 4 字節，InnoDB 單列索引長度上限 767 字節（MySQL 5.7+ / 開啟 innodb_large_prefix 可提升至 3072），設計 VARCHAR 長度時預留餘量（如 VARCHAR(191)）。
排序規則選擇：utf8mb4_unicode_ci 基於 UCA 標準，準確性高；utf8mb4_general_ci 速度略快但對某些語言排序不準。推薦 unicode_ci。
備份工具：mysqldump 需加 --default-character-set=utf8mb4 參數，防止導出亂碼。


完成上述遷移後，線上業務再寫入 Emoji 表情將不再報錯，徹底解決「Incorrect string value」難題。