怎样解决 Docker 容器内的乱码问题

解决Docker容器内中文乱码需同时配置UTF-8编码环境（如ENV LANG=C.UTF-8）和注入中文字体（如wqy-microhei），并分别验证locale、fc-list及文本输出。

解决 Docker 容器内中文乱码，关键在于同时补全两个环节：字符编码环境和中文字体支持。只改 LANG 变量或只装字体，都容易反复出问题。

确认当前乱码类型

先区分是“方块/问号”还是“锟斤拷”类乱码：

• 显示为 □ 或 ? → 字体缺失（系统知道这是中文，但画不出来）
• 显示为 、锟斤拷、æ–‡ → 编码不匹配（系统根本没用 UTF-8 解析字节流）

进入容器执行以下命令快速诊断：

locale —— 查看当前 LANG/LC_ALL 是否为 UTF-8 类值（如 C.UTF-8、zh_CN.UTF-8）
locale -a | grep -i utf —— 看系统是否预装了 UTF-8 locale
fc-list :lang=zh —— 检查是否有中文字体可用（返回空即缺字体）

统一配置 UTF-8 编码环境

不同基础镜像配置方式略有差异，优先推荐使用 C.UTF-8 —— 它是轻量、通用、无需额外语言包的 UTF-8 实现，比 zh_CN.UTF-8 更适合容器场景。

• Ubuntu/Debian 镜像：在 Dockerfile 中添加
  

  RUN apt-get update && apt-get install -y locales && <br>    locale-gen C.UTF-8 && <br>    update-locale LANG=C.UTF-8 LC_ALL=C.UTF-8

  
  并设置环境变量：ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
• Alpine 镜像：安装 musl-locales
  

  RUN apk add --no-cache tzdata musl-locales && <br>    cp /usr/share/locale/C.UTF-8/LC_ALL /etc/locale.conf

  
  再加：ENV LANG=C.UTF-8
• OpenJDK slim 镜像（如 openjdk:17-jre-slim）：直接设 ENV 即可生效，无需生成 locale
  ENV LANG=C.UTF-8 LC_ALL=C.UTF-8

注入可靠中文字体

字体必须满足两点：合法可用 + 被 Java/PDF/图像库实际识别。不建议直接复制 Windows simsun.ttc（版权风险），推荐开源字体：

• 文泉驿微米黑（wqy-microhei）：兼容性好，无版权顾虑
  RUN apt-get update && apt-get install -y fonts-wqy-microhei
• 或手动挂载（适合多容器复用）：
  宿主机准备字体目录：/usr/local/share/fonts/chinese/wqy-microhei.ttc
  运行时挂载：docker run -v /usr/local/share/fonts/chinese:/usr/share/fonts/chinese ...
  进容器后刷新缓存：fc-cache -fv
• Java 应用需额外指定字体路径（尤其 PDF 生成）：
  JVM 启动参数加：-Dawt.useSystemAAFontSettings=lcd -Dswing.aatext=true
  必要时在代码中显式加载：Font.createFont(Font.TRUETYPE_FONT, fontStream)

验证与收尾

容器启动后，执行三步验证：

• 检查编码：locale 输出应含 LANG=C.UTF-8
• 检查字体：fc-list :lang=zh | head -3 应列出中文字体名
• 模拟输出：echo "测试中文" > /tmp/test.txt && cat /tmp/test.txt，终端中应正常显示

若仍乱码，重点排查应用层：Java 加 -Dfile.encoding=UTF-8；Python 确保 sys.getdefaultencoding() == 'utf-8'；日志框架（如 Logback）配置 charset="UTF-8"。