快捷導(dǎo)航

Docker Compose 部署 MySQL 中文亂碼避坑指南

更新時間：2026年05月26日 08:32:30 作者：PythonAI實戰(zhàn)君

本文主要介紹了Docker Compose 部署 MySQL 中文亂碼避坑指南,文中通過示例代碼介紹的非常詳細,對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧

問題現(xiàn)象

使用 Docker Compose 部署若依后臺管理系統(tǒng)時，遇到以下中文亂碼問題：

Navicat 查詢中文亂碼：數(shù)據(jù)庫表中的中文字段顯示為亂碼（如 è‹¥ä¾?ç§‘æŠ€）
系統(tǒng)菜單接口返回亂碼：前端頁面菜單名稱、部門名稱等中文內(nèi)容顯示異常
后端日志中的中文也是亂碼

根本原因

MySQL 官方 Docker 鏡像在執(zhí)行 /docker-entrypoint-initdb.d/*.sql 初始化腳本時，默認使用 latin1 客戶端字符集，導(dǎo)致 UTF-8 編碼的 SQL 文件被錯誤解析。

即使你在 docker-compose.yml 中配置了：

command: >
  --character-set-server=utf8mb4
  --collation-server=utf8mb4_unicode_ci

這些參數(shù)只影響 MySQL Server 運行時的字符集，不影響 entrypoint 執(zhí)行初始化腳本時的客戶端字符集。

踩坑過程

坑 1：以為配置了 server 字符集就萬事大吉

# 錯誤示范 ?
command: >
  --character-set-server=utf8mb4
  --collation-server=utf8mb4_unicode_ci

結(jié)果：

SHOW VARIABLES LIKE 'character_set_server'; → utf8mb4 ?
但初始化后的數(shù)據(jù)仍然是亂碼 ?

坑 2：SQL 文件開頭加SET NAMES utf8mb4

-- 無效 ?
SET NAMES utf8mb4;
SET CHARACTER SET utf8mb4;

結(jié)果：entrypoint 執(zhí)行 SQL 時，第一個連接就已經(jīng)是 latin1，SET NAMES 只能修復(fù)后續(xù)語句，但前面的數(shù)據(jù)已經(jīng)寫入亂碼。

坑 3：掛載 my.cnf 配置文件

volumes:
  - ./mysql/conf/my.cnf:/etc/mysql/conf.d/my.cnf

結(jié)果：

World-writable config file '/etc/mysql/conf.d/my.cnf' is ignored.

Windows 掛載到 Docker 后文件權(quán)限變成 777，MySQL 出于安全考慮直接忽略該配置。

坑 4：使用--skip-character-set-client-handshake

command: >
  --skip-character-set-client-handshake

結(jié)果：這個參數(shù)確實能讓客戶端強制使用 server 字符集，但 entrypoint 執(zhí)行初始化腳本時可能尚未生效，導(dǎo)致初始化數(shù)據(jù)仍然亂碼。

正確解決方案

方案：Shell 腳本包裝器（推薦）

創(chuàng)建 00-init-database.sh，顯式指定 --default-character-set=utf8mb4 執(zhí)行 SQL：

#!/bin/bash
set -e
# 使用 utf8mb4 字符集執(zhí)行初始化 SQL
mysql -uroot -p"$MYSQL_ROOT_PASSWORD" --default-character-set=utf8mb4 < /docker-entrypoint-initdb.d/01-init.sql

SQL 文件（01-init.sql）：

USE `ry-vue`;
-- 建表 + 插入數(shù)據(jù)...

關(guān)鍵點：

.sh 腳本在 .sql 之前執(zhí)行（按文件名排序）
mysql 命令顯式指定 --default-character-set=utf8mb4
SQL 文件中包含 USE db_name;

完整 docker-compose.yml 配置

services:
  mysql:
    image: docker.1ms.run/mysql:8.0
    container_name: ruoyi-mysql
    environment:
      MYSQL_ROOT_PASSWORD: ruoyi123456
      MYSQL_DATABASE: ry-vue
      TZ: Asia/Shanghai
    command: >
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --default-time-zone=+08:00
    volumes:
      - ./mysql_data:/var/lib/mysql
      - ./mysql/init:/docker-entrypoint-initdb.d
    ports:
      - "3306:3306"

目錄結(jié)構(gòu)

docker/mysql/init/
├── 00-init-database.sh    # Shell 包裝器（關(guān)鍵！）
└── 01-init.sql            # 數(shù)據(jù)庫初始化 SQL

驗證方法

1. 檢查 MySQL 字符集

docker exec ruoyi-mysql mysql -uroot -p -e "SHOW VARIABLES LIKE 'character_set%';"

期望結(jié)果：

+--------------------------+---------+
| Variable_name            | Value   |
+--------------------------+---------+
| character_set_client     | utf8mb4 |
| character_set_connection | utf8mb4 |
| character_set_database   | utf8mb4 |
| character_set_results    | utf8mb4 |
| character_set_server     | utf8mb4 |
+--------------------------+---------+

2. 檢查數(shù)據(jù)是否正確

docker exec ruoyi-mysql sh -c 'mysql -uroot -p -e "SELECT dept_name FROM \`ry-vue\`.sys_dept WHERE dept_id=100;"'

期望結(jié)果：

dept_name
若依科技

3. Navicat 連接設(shè)置

編碼：選擇 Auto 或 utf8mb4
高級 → 編碼：65001 (UTF-8)

總結(jié)

方案	效果	原因
--character-set-server=utf8mb4	? 無效	只影響 server，不影響初始化客戶端
SQL 中加 SET NAMES utf8mb4	? 無效	執(zhí)行時已用 latin1 連接
掛載 my.cnf	? 無效	Windows 權(quán)限問題被忽略
--skip-character-set-client-handshake	?? 不穩(wěn)定	entrypoint 執(zhí)行時機不確定
Shell 腳本 + --default-character-set=utf8mb4	? 有效	直接控制初始化連接的字符集