RuoYi-Vue-Plus Docker 部署踩坑：MySQL 中文双重编码的根因与修复

现象用 docker-compose 部署完 RuoYi-Vue-Plus 后打开前端页面✅正常按钮文字「新增」「修改」「删除」、表头「角色名称」「权限字符」❌乱码左侧菜单、面包屑、表格中的中文角色名乱码长这样系统管ç†、租户管ç†看到这个 pattern 第一反应是编码问题但问题出在哪一环排查过程Step 1排除 Nginx先看 Nginx 的 Content-Type 头curl -sI http://127.0.0.1:88/ # Content-Type: text/html; charsetutf-8 ✅Nginx 没问题。Step 2排除前端 JS 编码检查编译产物的 UTF-8 字节# 系统 的 UTF-8 应该是 e7 b3 bb xxd /usr/share/nginx/html/assets/index-*.js | grep e7b3 # 找到了UTF-8 字节是正确的前端也没问题。Step 3检查 API 响应原始字节这是关键一步。用 Python 直接读取 API 返回的原始字节import urllib.request # ... login 省略 ... resp urllib.request.urlopen(req) raw resp.read() print(repr(raw[:200]))输出b{meta:{title:\\xc3\\xa7\\xc2\\xb3\\xc2\\xbb...发现问题了正常系统管理的 UTF-8 应该是\xe7\xb3\xbb\xe7\xbb\x9f\xe7\xae\xa1\xe7\x90\x86但实际返回的是\xc3\xa7\xc2\xb3\xc2\xbb\xc3\xa7\xc2\xbb...每个原始 UTF-8 字节前面都多了一个\xc3或\xc2。这就是经典的Mojibake双重编码原始 UTF-8: E7 B3 BB → 系 被当 Latin-1: ç ³ » → 3 个 Latin-1 字符 再 UTF-8 编码: C3 A7 C2 B3 C2 BB → 6 个字节Step 4确认是数据库层的问题直接查 MySQLSELECT menu_name, HEX(menu_name), LENGTH(menu_name), CHAR_LENGTH(menu_name) FROM sys_menu WHERE menu_id 1;-------------------------------------------------------------------------------- | menu_name| HEX(menu_name) | LENGTH | CHAR_LENGTH | -------------------------------------------------------------------------------- | 系统管理 | C3A7C2B3C2BBC3A7C2BBC5B8C3A7C2AEC2A1C3A7... | 25 | 12 | --------------------------------------------------------------------------------CHAR_LENGTH 12MySQL 以为这是 12 个字符实际是 12 个 Latin-1 字符LENGTH 25实际 25 个字节正确的系统管理应该是CHAR_LENGTH 4LENGTH 12HEX 为E7B3BBE7BB9FE7AEA1E79086数据库里存的就是双重编码的数据Step 5定位 MySQL 初始化的 charset 问题检查 MySQL 连接的字符集SHOW SESSION VARIABLES LIKE character_set%;| character_set_client | latin1 | | character_set_connection | latin1 | | character_set_results | latin1 | | character_set_server | utf8mb4 |虽然character_set_server utf8mb4但character_set_client latin1问题链条SQL 文件 (UTF-8: 系统管理 E7B3BB E7BB9F E7AEA1 E79086) ↓ mysql 客户端 (character_set_client latin1) ↓ MySQL 服务器认为输入是 Latin-1按 Latin-1 存储 ↓ 每个 UTF-8 字节被当成独立的 Latin-1 字符 ↓ 存储结果变成双重编码: C3A7C2B3C2BB...为什么--character-set-serverutf8mb4不够你的 docker-compose.yml 可能已经配了mysql: image: mysql:8.0 command: --character-set-serverutf8mb4 --collation-serverutf8mb4_general_ci但这只设置了服务端server的默认字符集。docker-entrypoint-initdb.d执行 SQL 文件时用的是mysql 客户端连接而 mysql 客户端的character_set_client默认取决于操作系统 locale。MySQL 官方 Docker 镜像基于 Oracle Linux / Debian默认 locale 是C或POSIX映射到 MySQL 就是latin1。所以即使你设了--character-set-serverutf8mb4initdb 阶段的 mysql 客户端连接仍然是 latin1。为什么--init-connect也不行你可能试过command: --init-connectSET NAMES utf8mb4--init-connect对root 用户不生效MySQL 安全策略。而docker-entrypoint-initdb.d的 SQL 就是用 root 执行的所以这个配置完全无效。修复方案在每个 SQL 文件的第一行加SET NAMES utf8mb4;SET NAMES utf8mb4; -- ---------------------------- -- 原来的内容... -- ---------------------------- create table sys_social ( ... );然后删除数据卷重新初始化docker compose down -v # 删除数据卷 docker compose up -d # 重新启动重新执行 initdb.d验证SELECT menu_name, HEX(menu_name), CHAR_LENGTH(menu_name) FROM sys_menu WHERE menu_id 1;---------------------------------------------------------- | menu_name| HEX(menu_name) | CHAR_LENGTH | ---------------------------------------------------------- | 系统管理 | E7B3BBE7BB9FE7AEA1E79086 | 4 | ----------------------------------------------------------CHAR_LENGTH 4HEX 是正确的 UTF-8搞定。其他方案对比方案是否有效原因--character-set-serverutf8mb4❌只影响 server 层不影响 client 连接--init-connectSET NAMES utf8mb4❌root 用户不执行 init_connect-e LANGC.UTF-8⚠️ 部分只对 BMP 字符有效emoji 等扩展字符仍有问题[client] default-character-setutf8mb4✅在 my.cnf 里配置但需要挂载自定义配置文件SQL 文件头部加SET NAMES utf8mb4;✅最简单、最可靠不依赖任何外部配置为什么这个问题很难排查静态文字正常Vue 模板里的中文按钮不受影响只有数据库返回的动态数据乱码乱码不是问号不是典型的???或方块而是系统这种看起来像编码问题但又不太确定的字符串server charset 误导SHOW VARIABLES显示character_set_serverutf8mb4让人以为配置没问题SQL 文件本身是 UTF-8用file命令检查 SQL 文件确实是 UTF-8但写入时被 mysql 客户端转码了总结MySQL Docker 镜像的docker-entrypoint-initdb.d机制mysql 客户端默认 charset 是 latin1 而不是 utf8mb4。这是一个从 2016 年就有人报告的问题docker-library/mysql#131、#708至今仍是默认行为。如果你的 SQL 文件包含非 ASCII 字符中文、日文、韩文、emoji 等务必在每个 SQL 文件的第一行加SET NAMES utf8mb4;否则数据会被双重编码写入数据库。