基于 RuoYi-Vue + MySQL 8.0 Docker 部署踩坑實(shí)錄

問(wèn)題現(xiàn)象

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

1. Navicat 查詢(xún)中文亂碼：數(shù)據(jù)庫(kù)表中的中文字段顯示為亂碼（如 若�科技）
2. 系統(tǒng)菜單接口返回亂碼：前端頁(yè)面菜單名稱(chēng)、部門(mén)名稱(chēng)等中文內(nèi)容顯示異常
3. 后端日志中的中文也是亂碼

根本原因

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

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

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

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

踩坑過(guò)程

坑 1：以為配置了 server 字符集就萬(wàn)事大吉

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

結(jié)果：

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

坑 2：SQL 文件開(kāi)頭加SET NAMES utf8mb4

-- 無(wú)效 ?
SET NAMES utf8mb4;
SET CHARACTER SET utf8mb4;

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

坑 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é)果：這個(gè)參數(shù)確實(shí)能讓客戶(hù)端強(qiáng)制使用 server 字符集，但 entrypoint 執(zhí)行初始化腳本時(shí)可能尚未生效，導(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)鍵點(diǎn)：

1. .sh 腳本在 .sql 之前執(zhí)行（按文件名排序）
2. mysql 命令顯式指定 --default-character-set=utf8mb4
3. 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ù)庫(kù)初始化 SQL

驗(yàn)證方法

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
• 高級(jí) → 編碼：65001 (UTF-8)

總結(jié)

一句話(huà)總結(jié)

Docker 部署 MySQL 時(shí)，初始化 SQL 一定要用 Shell 腳本包裝，顯式指定 --default-character-set=utf8mb4，否則中文必亂碼！

到此這篇關(guān)于Docker Compose 部署 MySQL 中文亂碼避坑指南的文章就介紹到這了,更多相關(guān)Docker Compose 部署 MySQL 中文亂碼內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論