我的表用的是 utf8 字符集、自以为能存下任何 Unicode 文字,直到用户昵称里带了个 emoji 表情,插入直接报 Incorrect string value 整条写入失败,我盯着这个号称万国码的 utf8 百思不得其解,最后才搞懂 MySQL 里那个叫 utf8 的东西其实只是阉割版、最多只存得下三字节的字符

这是一次让我把 MySQL 里"utf8 字符集"这件事,从"万国码、能存任何 Unicode",重新理解成"它其实是个阉割版、最多只存三字节字符、存不下 emoji"的事故。我的表用的是 utf8 字符集,自以为能存下任何 Unicode 文字。直到用户昵称里带了个 emoji 表情,插入直接报 Incorrect string value、整条写入失败。我盯着这个号称"万国码"的 utf8 百思不得其解,最后才搞懂:MySQL 里那个叫 utf8 的东西其实只是阉割版,最多只存得下三字节的字符。这篇就把这次"utf8 存不下 emoji"的事故,从头到尾复盘一遍。

故障现场:昵称带了个 emoji,整条插入就报错

我的用户表、评论表都用的 utf8 字符集。我一直觉得很放心——utf8 不就是 UTF-8 嘛,Unicode 万国码,中文、日文、韩文、各种符号,什么字都能存,这是常识。系统跑了很久,中英日文混排都好好的。

可某天开始,部分用户的操作频繁报错:他们在昵称、评论里输入了 emoji 表情(😀、🎉 之类),数据库插入时直接抛 ERROR 1366: Incorrect string value: '\\xF0\\x9F\\x98\\x80...',整条记录写入失败;有的配置下不报错、但 emoji 后面的内容被静默截断了。我一开始很懵:utf8 不是万国码吗,emoji 也是 Unicode 字符,怎么会存不进去? 我反复确认列就是 utf8、连接编码也是 utf8。直到我去查那个错误里的字节 \\xF0\\x9F...,以及 MySQL 的 utf8 到底是什么,才彻底明白根因——MySQL 里的 utf8,并不是完整的、标准的 UTF-8!它实际上是 utf8mb3 的别名——一个"最多只用 3 个字节编码一个字符"的阉割版 UTF-8。而标准 UTF-8 里,一个字符最多可以用 4 个字节编码;那些需要 4 字节的字符——包括几乎所有 emoji 表情、以及一些生僻汉字、某些古文字符——在 MySQL 的 utf8 里根本无法表示。emoji 😀 的 UTF-8 编码是 F0 9F 98 80 四个字节,而 MySQL 的 utf8 列只认最多 3 字节的字符,遇到这个 4 字节的家伙,要么报 Incorrect string value 拒绝插入,要么(在宽松模式下)从那个 4 字节字符处把字符串截断。也就是说,MySQL 的 utf8 从一开始就不是"能存任何 Unicode"的完整 UTF-8,它只是 UTF-8 的一个三字节子集;真正完整支持全部 Unicode(含 4 字节字符)的,是另一个叫 utf8mb4 的字符集(mb4 = most bytes 4)。我被 utf8 这个名字骗了——我理所当然地以为它就是那个"能存万国文字"的 UTF-8,却不知道 MySQL 给这个名字安的,是一个存不下 emoji 的阉割实现。

-- 我的表: 用了 utf8(以为是完整 UTF-8, 能存任何 Unicode)
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    nickname VARCHAR(50)
) CHARSET=utf8;            -- ★ MySQL 的 utf8 其实是 utf8mb3, 最多 3 字节/字符

-- 用户昵称带 emoji:
INSERT INTO users VALUES (1, '小明😀');
-- ✗ ERROR 1366: Incorrect string value: '\xF0\x9F\x98\x80' for column 'nickname'
--   (宽松 sql_mode 下: 不报错, 但 😀 及之后被静默截断 → 存进去成了 '小明')

-- 真相: emoji 😀 的 UTF-8 是 4 字节(F0 9F 98 80),
--   而 MySQL 的 utf8 = utf8mb3, 最多只支持 3 字节/字符, 存不下 4 字节的
--   标准 UTF-8 一个字符最多 4 字节; emoji/生僻字/古文字都需要 4 字节
--   MySQL 真正完整支持全部 Unicode 的是 utf8mb4(most bytes 4)

-- utf8 这个名字骗了我: 它不是完整 UTF-8, 只是 3 字节子集

问题被钉死在这个认知错位上:我以为 MySQL 的 utf8 字符集就是"那个能存任何 Unicode 字符的 UTF-8"——名字都叫 utf8 了,不就是 UTF-8 吗?但 MySQL 的 utf8 实际是 utf8mb3,一个"每个字符最多 3 字节"的阉割版 UTF-8,它只能表示 Unicode 里那些 3 字节以内的字符,而存不下需要 4 字节的字符(emoji、部分生僻字等)。名字 "utf8" 给了我"完整 UTF-8"的暗示,可它的实际能力只是 UTF-8 的一个子集。我被这个名字误导,理所当然地以为它具备名字所暗示的"万国码"全部能力,从没去核实它的实际规格(最多几字节);直到一个 4 字节的 emoji 撞上来,这个"名不副实"的真相才暴露。我把"名字叫 utf8"当成了"就是完整的 UTF-8",而没意识到名字的暗示和实际能力之间,隔着一个 MySQL 历史遗留的、坑了无数人的别名。我以为我用的是那把能开所有 Unicode 锁的万能钥匙,其实它只是个被磨掉了一截、开不了四字节那类锁的仿制品,而它偏偏还叫着万能钥匙的名字。

第一件事:想明白 MySQL 的 utf8 是 utf8mb3、要用 utf8mb4

把这次事故彻底想清楚,关键是理解MySQL 里的字符集 utf8 是 utf8mb3 的别名(历史遗留),它每个字符最多用 3 个字节编码,只能表示 Unicode 基本多文种平面(BMP)内的字符;而标准 UTF-8 每个字符最多 4 个字节,4 字节的字符(几乎所有 emoji、一些 CJK 扩展区的生僻汉字、某些符号和古文字)在 MySQL 的 utf8 里无法存储——严格 sql_mode 下报 Incorrect string value 拒绝,宽松模式下从该字符处截断。MySQL 里真正完整支持全部 Unicode(含 4 字节字符)的字符集是 utf8mb4(most bytes 4)。

所以正确的做法很明确:凡是可能存储用户输入文本(昵称、评论、消息、富文本)的列,一律用 utf8mb4 字符集(及配套的 collation,如 utf8mb4_unicode_ci 或 utf8mb4_0900_ai_ci),而不是 utf8;并且要确保从表到连接的整条链路都是 utf8mb4——库/表/列的字符集是 utf8mb4、客户端连接的字符集也要设成 utf8mb4(连接参数 characterEncoding=utf8mb4 或执行 SET NAMES utf8mb4),否则即使列是 utf8mb4、连接是 utf8,emoji 还是会在连接这一层丢掉。新项目直接默认 utf8mb4;老项目有 utf8 列要 ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4 迁移(注意 utf8mb4 一个字符占更多字节,可能影响索引长度上限,需留意)。关键认知是:不要被一个东西的名字/标签的暗示所误导、想当然地以为它具备名字所暗示的全部能力;名字可能因历史、营销、习惯等原因而名不副实,只是真实事物的一个别名、子集或近似。要按它的实际规格、实际能力(这里是"每个字符最多几字节、能不能存 4 字节字符")去判断它能不能满足你的需求,而不是凭它的名字想当然。

-- 正解1: 新建表用 utf8mb4(完整 UTF-8, 能存 emoji 和所有 Unicode)
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    nickname VARCHAR(50)
) CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;   -- 或 utf8mb4_unicode_ci

INSERT INTO users VALUES (1, '小明😀');          -- ✓ emoji 正常存入

-- 正解2: 老表迁移 —— 把 utf8 列转成 utf8mb4
ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 注意: utf8mb4 每字符最多 4 字节, VARCHAR/索引的字节长度上限要复核
--   (如旧的 VARCHAR(255) 索引在 utf8mb4 下可能超过单列索引长度限制)

-- 正解3: 整条链路都要 utf8mb4 —— 列对了, 连接也得对
--   JDBC: jdbc:mysql://.../db?characterEncoding=utf8mb4
--   或连接后执行: SET NAMES utf8mb4;
--   否则连接层还是 utf8, emoji 在传输时就被丢了

-- 自检: 确认库/表/列和连接都是 utf8mb4
SHOW VARIABLES LIKE 'character_set%';   -- 看连接相关的字符集
SHOW CREATE TABLE users;                -- 看表/列字符集是不是 utf8mb4

想通这一层,我才明白自己错在哪:我把 MySQL 的 utf8 当成了"完整的、能存万国文字的 UTF-8",仅仅因为它叫这个名字;却不知道它实际是 utf8mb3——一个每字符最多 3 字节、存不下 emoji 等 4 字节字符的阉割版。我被名字的暗示骗了,没去核实它的实际规格,直到一个 4 字节的 emoji 把这个"名不副实"撕开。根治之道,是凡存用户文本一律用 utf8mb4(完整 UTF-8)、且确保从表到连接整条链路都是 utf8mb4。不是凭名字想当然以为它有名字暗示的能力,而是核实它的实际规格、按实际能力选用。

第二件事:正解——用 utf8mb4,且从库表列到连接整条链路都是 utf8mb4

找到根因,正解就清晰了:凡是可能存用户输入文本的列一律用 utf8mb4(完整 UTF-8、能存 emoji 和所有 Unicode)及配套 collation;并确保从库/表/列到客户端连接整条链路都是 utf8mb4(连接参数或 SET NAMES utf8mb4),否则连接层还是 utf8 时 emoji 仍会丢;老项目把 utf8 列 CONVERT TO CHARACTER SET utf8mb4 迁移、并复核索引长度。

-- 错误: 用 utf8(=utf8mb3), 存不下 emoji
CREATE TABLE t (name VARCHAR(50)) CHARSET=utf8;       -- ✗

-- 正解1: 新表用 utf8mb4 + 配套 collation
CREATE TABLE t (
    name VARCHAR(50)
) CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;          -- 或 utf8mb4_unicode_ci

-- 正解2: 老表迁移到 utf8mb4(注意复核索引长度上限)
ALTER TABLE t CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 正解3: 设库的默认字符集, 新表自动继承
ALTER DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 正解4: 连接层也必须 utf8mb4(否则列对了连接丢)
SET NAMES utf8mb4;
-- JDBC: ?characterEncoding=utf8mb4  (老驱动用等价配置)
-- 各语言驱动连接参数里指定 charset=utf8mb4

-- 自检: 确认整条链路都是 utf8mb4
SHOW CREATE TABLE t;                       -- 表/列字符集
SHOW VARIABLES LIKE 'character_set%';      -- client/connection/results 都应是 utf8mb4

这套做法的精髓,是选一个真正具备你需要的能力(完整 UTF-8、能存 4 字节字符)的字符集 utf8mb4,而不是被名字误导用了阉割的 utf8;并且要让这个能力贯穿整条链路——存储层、连接层、客户端都一致,任何一段是 utf8(mb3),emoji 就会在那一段丢失。列是 utf8mb4 但连接是 utf8,emoji 在传输时就被丢了——所以"表到连接全链路 utf8mb4"缺一不可。老项目迁移时注意 utf8mb4 每字符占更多字节、VARCHAR 索引长度上限要复核。不是凭名字以为 utf8 够用,而是按实际能力选 utf8mb4、并让它贯穿全链路。

【MySQL 字符集存中文/emoji, 我现在认死的几条】

1. MySQL 的 utf8 = utf8mb3, 每字符最多 3 字节, 存不下 emoji 等 4 字节字符

2. utf8 这个名字名不副实, 它不是完整 UTF-8, 只是 3 字节子集

3. 标准 UTF-8 每字符最多 4 字节; emoji/生僻字/古文字需 4 字节

4. 存用户输入文本一律用 utf8mb4(完整 UTF-8)+ 配套 collation

5. 整条链路都要 utf8mb4: 库/表/列 + 客户端连接(SET NAMES/连接参数)

6. 老表迁移 CONVERT TO CHARACTER SET utf8mb4, 复核 VARCHAR 索引长度上限

7. 通用: 别被名字暗示骗, 按实际规格(每字符几字节)判断能力

第三件事:其他"被名字/标签的暗示误导、以为它有名字暗示的能力"的同类坑

顺着"被一个东西的名字/标签暗示误导、想当然以为它具备名字所暗示的全部能力、实则名不副实"这条线,我把同类的坑都排查了一遍:

第一个,VARCHAR(50) 的 50 是字符数不是字节数(或反之,因 DB 而异)。想当然以为单位是字符或字节,在多字节字符下存不下或浪费,要核实该 DB 的实际单位。

第二个,TIMESTAMP "带时区" 的误解。以为它存的是带时区的绝对时间,其实行为依赖会话时区设置,名字给的暗示和实际语义有出入。

第三个,FLOAT/DOUBLE 当"精确小数"用。名字像能存小数,但它是二进制浮点、存不下精确十进制,金额要用 DECIMAL。

第四个,"线程安全"的类只是部分方法安全。看到"线程安全"就以为怎么用都安全,其实可能只有单个方法原子、复合操作仍需外部同步,要看实际保证。

第四件事:utf8(mb3) vs utf8mb4——一张对照表

我把 MySQL 的两个 UTF-8 字符集摆在一起对比,核心看"能存什么、该用哪个":

看清这张表,选择就毫无悬念:存任何用户文本一律用 utf8mb4(完整 UTF-8、能存 emoji 和全部 Unicode);MySQL 的 utf8(mb3)是历史遗留的 3 字节阉割版,别再用。我这次踩坑,正是被 utf8 这个名字骗了、以为它是完整 UTF-8,结果一个 emoji 就把它存不下 4 字节字符的真相暴露了。按实际能力(每字符最多几字节)选,而不是按名字想当然。

第五件事:我曾经对 MySQL utf8 想当然的几个误区

这次事故也把我对字符集的一堆"想当然"照了个底朝天:

这些误区的根子是同一个:我把一个东西的名字所暗示的能力,当成了它实际具备的能力——"它叫 utf8,那它当然就是完整的 UTF-8、能存万国文字"。可名字会因为历史、习惯、向后兼容等原因而名不副实:MySQL 当年把"utf8"这个名字给了一个 3 字节的子集实现,等真正完整的来了只好叫 utf8mb4,于是 "utf8" 就成了一个误导无数人的别名。我从没去核实它"每字符到底支持几字节"这个实际规格,只凭名字就笃定了它的能力。把"名字的暗示"当成"实际的能力",不去核实真实规格,是这类被名字误导的共同根源。

第六件事:选字符集、排查"emoji/某些字存不进去"时,我现在的自检习惯

现在每当我选数据库字符集、或排查"emoji 或某些字符存进去报错/被截断",我都会先按这张图问自己:

这张图的精髓,是"emoji 存不下先看字符集是不是 utf8(mb3);改成 utf8mb4 且库表列到连接全链路都要 utf8mb4"。设计就存用户文本一律 utf8mb4、整条链路(库/表/列+连接)都 utf8mb4、迁移复核索引长度、排查就看出问题的列和连接字符集是不是 utf8(mb3)。这套习惯,让我从"utf8 就是 UTF-8 够用"变成了"核实它每字符几字节、存用户文本必用 utf8mb4"——核心始终是:MySQL 里的字符集 utf8 是 utf8mb3 的别名(历史遗留),它每个字符最多用 3 个字节编码、只能表示 Unicode 基本多文种平面 BMP 内的字符,而标准 UTF-8 每个字符最多 4 个字节,4 字节的字符(几乎所有 emoji、一些 CJK 扩展区的生僻汉字、某些符号和古文字)在 MySQL 的 utf8 里无法存储——严格 sql_mode 下报 Incorrect string value 拒绝、宽松模式下从该字符处截断;MySQL 里真正完整支持全部 Unicode 含 4 字节字符的字符集是 utf8mb4(most bytes 4);所以凡是可能存储用户输入文本(昵称、评论、消息、富文本)的列一律用 utf8mb4 字符集及配套 collation 而不是 utf8,并且要确保从表到连接的整条链路都是 utf8mb4——库/表/列的字符集是 utf8mb4、客户端连接的字符集也要设成 utf8mb4(连接参数 characterEncoding=utf8mb4 或执行 SET NAMES utf8mb4),否则即使列是 utf8mb4 连接是 utf8 emoji 还是会在连接这一层丢掉,新项目直接默认 utf8mb4、老项目有 utf8 列要 ALTER TABLE CONVERT TO CHARACTER SET utf8mb4 迁移(注意 utf8mb4 一个字符占更多字节可能影响索引长度上限);一句话,不要被一个东西的名字/标签的暗示所误导想当然以为它具备名字所暗示的全部能力,名字可能因历史营销习惯等原因而名不副实只是真实事物的一个别名子集或近似,要按它的实际规格实际能力(这里是每个字符最多几字节、能不能存 4 字节字符)去判断它能不能满足你的需求而不是凭它的名字想当然。

我立下的几条规矩

这场"utf8 存不下 emoji"的事故,换来了我选数据库字符集时,刻进骨子里的几条铁律:

1. MySQL 的 utf8 = utf8mb3,每字符最多 3 字节,存不下 emoji 等 4 字节字符。
2. utf8 这个名字名不副实,它不是完整 UTF-8,只是 3 字节子集。
3. 标准 UTF-8 每字符最多 4 字节;emoji/生僻字/古文字需 4 字节。
4. 存用户输入文本一律用 utf8mb4(完整 UTF-8)+ 配套 collation。
5. 整条链路都要 utf8mb4:库/表/列 + 客户端连接(SET NAMES/连接参数)。
6. 老表迁移 CONVERT TO CHARACTER SET utf8mb4,复核 VARCHAR 索引长度上限。
7. 通用:别被名字暗示骗,按实际规格(每字符几字节)判断能力。

附:一段可直接照抄的 utf8mb4 排查与迁移清单

最后留一段我自己排查"emoji 存不进去"和迁移 utf8mb4 时照着跑的 SQL/命令清单:

-- 1. 看库/表/列当前的字符集(确认是不是 utf8=utf8mb3)
SHOW VARIABLES LIKE 'character_set_%';
SHOW CREATE TABLE users\G          -- 看 DEFAULT CHARSET 和各列 CHARACTER SET

-- 2. 把库默认改成 utf8mb4(新表会继承)
ALTER DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

-- 3. 把老表整表(含所有列里的数据)转成 utf8mb4
ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
-- 注意: utf8mb4 下一个字符最多 4 字节, VARCHAR(255) 索引可能超过长度上限,
-- 必要时缩短列长或改前缀索引 KEY idx_name (name(191))

-- 4. 确认连接层也是 utf8mb4(否则列对了 emoji 还是在连接层丢)
SHOW VARIABLES LIKE 'character_set_client';      -- 应为 utf8mb4
SHOW VARIABLES LIKE 'character_set_connection';  -- 应为 utf8mb4
-- 应用连接里执行(或在连接参数 characterEncoding=utf8mb4):
SET NAMES utf8mb4;

-- 5. 验证: 直接插一个 emoji 看能不能存能不能读回来
INSERT INTO users(name) VALUES ('test 😀 emoji');
SELECT name, HEX(name) FROM users WHERE name LIKE 'test%';
-- HEX 里能看到 F09F9880(😀 的 UTF-8 4 字节)就对了

这段清单的顺序就是结论本身:先看清当前是不是 utf8(mb3)→ 库/表/列转 utf8mb4(复核索引长度)→ 连接层也设 utf8mb4 → 插一个 emoji 验证 HEX 是 4 字节。整条链路都 utf8mb4,emoji 才真正存得下、读得回。

写在最后

回头看,这场由"utf8 不是完整 UTF-8"引发的"emoji 存不下"事故,真正教给我的,远不止"改用 utf8mb4"这一个技巧。它让我对"一个东西的'名字',和它'实际是什么、实际能做什么',并不总是一回事;名字是一个标签,它给我们一个关于这个东西能力的'暗示',而我们极容易把这个暗示直接当成事实——'它叫 X,那它当然就是 X、就具备 X 该有的一切';可名字常常因为历史包袱、向后兼容、营销习惯等原因而'名不副实':它可能只是真实事物的一个别名、一个子集、一个早期不完整的实现,真正完整的那个反而被迫换了个别扭的名字",有了一次刻骨的体会。我栽跟头,是因为我把 MySQL 那个字符集"名字叫 utf8"这件事,直接等同于了"它就是完整的、能存万国文字的 UTF-8"——名字都和标准编码一字不差了,我凭什么怀疑它?于是我连它"每个字符到底支持几字节"这个最基本的实际规格都没去看一眼;我不知道,MySQL 当年把 "utf8" 这个名字给了一个只支持 3 字节的早期实现,等真正完整的 4 字节实现来了,只好委屈地叫 "utf8mb4",于是 "utf8" 这个本该最名正言顺的名字,反而成了一个坑了无数人的、名不副实的别名;直到一个区区 4 字节的 emoji 撞上来,这个藏在名字背后的真相才被撕开——原来我信赖的"万国码",从一开始就装不下整个万国。这让我领悟到一个关于"名字与实质"的深刻认知:名字是对事物的一个指代和概括,但它不等于事物本身,更不保证它如实反映了事物的全部能力和边界;尤其在技术里,名字承载着大量历史:一个名字可能在不同年代、不同系统里指向不同的实现,可能因为先占了坑而让真正完整的版本只能另起别名,可能为了向后兼容而保留了一个早已名不副实的旧称;所以,当我们要依赖一个东西去满足某个具体需求时,真正可靠的依据,永远是它的实际规格、实际能力、实际边界(它到底支持什么、不支持什么、限制在哪),而不是它的名字给我们的那个想当然的暗示;把"它叫什么"当成"它是什么、它能做什么",是一种把标签误当本质的轻信——而消除它,只需要一个动作:在依赖它之前,去查一眼它真实的规格。这给了我一种看待"一切'凭名字判断一个东西能力'之事"时的清醒:每当我准备依赖一个东西(类型、字符集、库、API、配置项)去满足一个具体需求时,要追问"我对它能力的判断,是来自它的名字给我的暗示,还是来自它真实的规格?这个名字会不会名不副实——它是不是某个东西的子集、别名、或早期不完整实现?它的实际边界(能存什么、支持到什么程度)真的覆盖我的需求吗"——按实际规格而非名字暗示来判断和选用,依赖前先核实它真实的能力边界;"别把名字的暗示当能力、按实际规格判断和选用",是用对 MySQL 字符集、也是可靠地使用一切技术组件的关键。认清 MySQL 的 utf8 是 utf8mb3 只支持 3 字节、存 emoji 要 utf8mb4 且全链路一致、名字可能名不副实——这,是我用一次"一个 emoji 让整条插入失败"的事故,换来的、关于数据库、也关于如何分清名字与实质的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次建表随手写 CHARSET=utf8 时,先想一句"这是 utf8mb3 啊,存得下 emoji 吗?是不是该用 utf8mb4?",那我对着那条"因一个 emoji 而失败"的插入排查的大半天,就值了。

—— 别看了 · 2026