必须挂载自定义配置文件到 /etc/mysql/conf.d/,因 MySQL 8.0 官方镜像仅自动加载该目录下后缀为 .cnf 的文件(按字母序),忽略 /etc/mysql/my.cnf;需确保文件含 [mysqld] 等正确段落、权限为 644、挂载时加 :ro,否则配置不生效。

必须挂载自定义配置文件到 /etc/mysql/conf.d/
MySQL 8.0 Docker 镜像默认不启用 utf8mb4 的完整客户端-服务端协同,光靠环境变量或启动参数无法覆盖连接层字符集。镜像只自动加载 /etc/mysql/conf.d/ 下后缀为 .cnf 的文件,且按字母序读取——所以别把配置写进 /etc/mysql/my.cnf(它常被忽略),也别起名 z-charset.cnf(可能被其他配置覆盖)。
正确做法是创建一个 01-charset.cnf,内容如下:
[mysqld] character-set-server = utf8mb4 collation-server = utf8mb4_0900_ai_ci init_connect = 'SET NAMES utf8mb4' skip-character-set-client-handshake = ON [client] default-character-set = utf8mb4 [mysql] default-character-set = utf8mb4
然后启动容器时挂载:
docker run -v /path/to/01-charset.cnf:/etc/mysql/conf.d/01-charset.cnf:ro ... mysql:8.0
注意::ro 是必须的,Docker 官方镜像会拒绝加载可写配置;路径权限需为 644,否则静默跳过。
SHOW VARIABLES LIKE 'character%' 四项必须全为 utf8mb4
重启容器后,用 mysql -h 127.0.0.1 -P 3306 -u root -p 连上,立刻执行:
SHOW VARIABLES LIKE 'character\_set%';
你必须看到这四行值全部是 utf8mb4:
character_set_clientcharacter_set_connectioncharacter_set_resultscharacter_set_server
只要其中任一项是 utf8(即 utf8mb3)或 latin1,说明配置没生效。常见原因包括:[mysql] 段名拼错成 [mysqld]、挂载路径错误(比如挂到了 /etc/mysql/my.cnf 却没生效)、或者宿主机文件权限不是 644。
已有数据库和表必须手动转换,character-set-server 不影响旧对象
即使配置全对、四项变量全为 utf8mb4,老库老表默认仍用 utf8 或 latin1 字符集,插入 emoji 依然报 Incorrect string value。
分三步修复:
- 改库:
ALTER DATABASE db_name CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci; - 改表:
ALTER TABLE tbl_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; - 若仍有字段乱码(比如建表时显式写了
CHARACTER SET utf8),单独改列:ALTER TABLE tbl_name MODIFY column_name VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
特别注意:含索引的 VARCHAR 字段在 utf8mb4 下最大长度受限(如 VARCHAR(255) × 4 字节 = 1020 字节),超出 InnoDB 单列索引限制(767 字节)。此时需加 ROW_FORMAT=DYNAMIC 并确保 innodb_large_prefix=ON(MySQL 8.0 默认开启)。
应用连接串必须显式声明 charset=utf8mb4
Docker 容器内 MySQL 服务配得再完美,PHP、Python、Java 应用连上去时若没指定字符集,仍可能走默认 utf8 协商。这不是 bug,是协议设计如此。
示例:
- PHP PDO:
new PDO('mysql:host=localhost;dbname=test;charset=utf8mb4', $user, $pass); - Python PyMySQL:
charset='utf8mb4'参数不能省 - Java JDBC:
jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf8mb4
漏掉这个,哪怕数据库、表、字段全是 utf8mb4,中文或 emoji 在应用层仍可能变成 ? 或报错。这点最容易被忽略,因为本地测试时可能碰巧“看起来正常”,一上生产就出问题。


















