极客工场

Appearance

共 2,293 字预计阅读约 8 分钟

docker 容器内中文乱码速查：locale 与终端编码对齐 ​

更新时间：2026-10-24。FAQ 速查页，面向容器里中文变问号、变方块、docker logs 打出一堆 ??? 的同学。docker 中文乱码几乎从不是「容器把字符弄丢了」，而是编码链上某一环对不上：镜像里根本没有中文 locale、LANG 没设、程序按默认编码（往往是 ASCII 或 GBK）输出，而终端按 UTF-8 解码——同一段字节，两边各说各话。病灶收敛在六根轴上：镜像无 locale 数据、LANG/LC_ALL 未设置、精简基础镜像裁掉了 locale、应用日志编码与终端不一致、JVM 默认编码随平台漂移、程序内部写死编码。容器其它运行期怪相（卡死、崩溃）分别看 docker 容器卡死速查 与 docker 容器段错误速查。

本文要回答的问题 ​

  • 容器里 echo 中文 正常，但应用日志里全是 ???，差在哪一环？
  • locale 命令报 Cannot set LC_ALL，是镜像坏了吗？
  • alpine 镜像设了 LANG 为什么还是乱码？
  • 容器里文件内容中文正常，docker logs 看却是乱码？
  • 为什么同一个 Java 程序在宿主机好好的，进容器就乱码？

一、报错原文与典型现象 ​

乱码类问题没有「报错」，现象是三条线（路径以 /proj/demo 占位）：

bash
# 现象一：日志里的中文全部变问号
$ docker logs demo-app | tail -3
2026-10-24 10:00:01 INFO  ???????
2026-10-24 10:00:02 ERROR ??????
bash
# 现象二：locale 不存在，命令直接抱怨
$ docker exec demo-app locale
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
LANG=zh_CN.UTF-8
bash
# 现象三：容器内中文正常，docker logs 输出是方块/问号
$ docker exec demo-app cat /proj/demo/msg.txt
订单创建成功
$ docker logs demo-app
??????

读现象抓一个关键判别：容器内看正常、宿主机 docker logs 看乱码，是「终端/日志驱动解码端」的病；容器内看就乱码，是「容器内编码端」的病。问号 ? 通常是程序在编码阶段就替换掉了不认识的字符（数据已丢，事后救不回）；方块或 \xe4\xbd 形式的转义说明字节还在，只是显示端没按 UTF-8 解。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
locale 命令报 No such file or directory镜像没装 locale 数据locale -a 看可用列表装 locales/glibc-langpack 或改用 C.UTF-8
日志中文全变问号LANG 未设，程序按 ASCII 输出容器内 echo $LANG 为空镜像设 ENV LANG=C.UTF-8
alpine 设了 LANG 仍乱码musl 不自带 locale 数据locale -a 只有 C/POSIX装 musl-locales 或程序内显式 UTF-8
容器内正常、docker logs 乱码宿主机终端编码非 UTF-8宿主机 echo $LANG、locale终端改 UTF-8，SSH 客户端同步设置
Java 应用进容器才乱码JVM 默认编码随 locale 漂移打印 file.encoding 属性JVM 参数 -Dfile.encoding=UTF-8
只有某个接口/文件乱码程序写死 GBK 等编码查代码里 getBytes/解码处统一改 UTF-8，入口校验
数据库读出中文乱码连接串未指定字符集看 JDBC/DSN 参数连接串加 characterEncoding=utf8

三、排查决策图 ​

这张图是标准排查路线：红是乱码现象与命中的根因，蓝是排查动作，绿是验证通过，橙是修复，紫是防复发沉淀。

engineering/docker/ts-docker-encoding-locale.md D2 示意图

读这张图抓住分水岭动作：先在容器内直接 cat 一个已知中文文件。容器内就乱——病在容器侧（locale 与程序编码），顺着 LANG 与 locale -a 两刀切下去；容器内正常、只有 docker logs 乱——病在显示端（宿主机终端或 SSH 客户端编码），改容器没用。

四、逐条排查展开 ​

镜像没有 locale 数据是最底层的坑。 报错 Cannot set LC_CTYPE to default locale 的意思是：LANG 指向的 locale（比如 zh_CN.UTF-8）在镜像里根本没有对应的数据文件。先盘点镜像里有什么：

bash
docker exec demo-app locale -a
# 只输出 C / POSIX = 镜像没有任何 UTF-8 locale

处置按发行版走：Debian/Ubuntu 系 apt-get install -y locales && locale-gen zh_CN.UTF-8；RHEL/CentOS 系装 glibc-langpack-zh；更省事且更稳的做法是直接 ENV LANG=C.UTF-8——glibc 自带的 C.UTF-8 几乎所有现代镜像都有，对「程序能正确处理 UTF-8」这一目标已经足够，不必追求 zh_CN.UTF-8（它只额外影响排序、货币等本地化规则，一般服务用不上）。

LANG 未设是问号型乱码的头号根因。 很多程序（尤其 C 库生态的工具）按 locale 决定输出编码：LANG 为空时按 POSIX/C 处理，非 ASCII 字符在编码阶段就被替换成 ?——数据在写日志那一刻就丢了，事后改终端也救不回来。验证一刀：

bash
docker exec demo-app sh -c 'echo "$LANG"'
# 空输出 = 命中

在 Dockerfile 里固化：

dockerfile
ENV LANG=C.UTF-8 \
    LC_ALL=C.UTF-8

alpine 的 musl 另说。 alpine 用 musl libc，locale -a 常年只有 C 和 POSIX，设 LANG 也没人认。两条路：装 musl-locales 与 musl-locales-lang 包补上 locale 数据；或者在程序层面显式指定 UTF-8（Java 加 -Dfile.encoding=UTF-8、Python 设 PYTHONIOENCODING=utf-8、Go 本来就用 UTF-8 不受影响）。镜像能换的话，直接换 Debian slim 系基础镜像最省心。

「容器内正常、docker logs 乱码」是显示端的病。 字节本身是对的，是宿主机终端没按 UTF-8 解。按顺序查：宿主机 locale 看 LANG 是不是 UTF-8 系；Windows 终端（cmd/PowerShell 老代码页 936/GBK）切到 UTF-8 代码页 chcp 65001 或换 Windows Terminal；SSH 客户端（Xshell/SecureCRT 等）的会话编码单独设为 UTF-8——它不服从不锈钢务端的 locale，是独立一层。

JVM 默认编码随平台漂移是 Java 专属坑。 JVM 的 file.encoding 取宿环境 locale：宿主机是 UTF-8 所以好好的，进容器 LANG 为空就退成 ANSI_X3.4-1968（即 ASCII），中文一写日志就变问号。确认姿势是打印 System.getProperty("file.encoding")；处置是 JVM 参数钉死 -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8（后者管文件名/命令行参数的编码），别指望容器 locale 一定配得对。Spring Boot 新版本中 server.servlet.encoding 相关配置同理要显式 UTF-8。

程序内部写死编码是最后一颗雷。 前面五站都正常、只有某个接口或某个文件乱码时，基本能锁定代码里有 getBytes("GBK")、new String(bytes, "GB2312") 这类硬编码——常见于从老系统迁移来的模块。这类乱码容器化只是放大器（宿主机 locale 恰好兜住了），根治是统一 UTF-8 并在代码评审里把编码参数列进检查清单。

数据库连接串是乱码的隐蔽源头。 容器内程序读写 MySQL 时，服务端、库表、连接三层字符集任何一层不是 utf8mb4，中文就会在进出库的路上变形——典型表现是「日志里写之前还是好的，读出来就乱了」。确认姿势是连进库执行 SHOW VARIABLES LIKE 'character_set%' 三行对照；处置是 JDBC 连接串显式 useUnicode=true&characterEncoding=utf8（MySQL 8 驱动写作 utf8mb4），建库建表默认字符集一并钉死，别依赖服务端全局配置恰好是对的。

五、规范做法与预防 ​

  • 基础镜像模板内置 UTF-8 环境：ENV LANG=C.UTF-8 LC_ALL=C.UTF-8 写进公司基础镜像，业务镜像默认继承。
  • locale 数据按需装：Debian 系装 locales 并 locale-gen；alpine 装 musl-locales 或干脆换基础镜像。
  • JVM 参数钉死编码：-Dfile.encoding=UTF-8 进启动脚本模板，不依赖环境 locale。
  • 日志框架显式 UTF-8：logback/log4j2 的 PatternLayout/编码器显式 charset=UTF-8。
  • CI 卡口：镜像构建后跑一条 docker run <img> sh -c 'echo $LANG'，为空直接判失败。
  • 数据库三层字符集对齐：服务端、库表、连接串统一 utf8mb4，连接串显式写 characterEncoding。
  • 数据已变问号不可恢复：问号是编码阶段丢弃，预防重于补救——上线前用中文用例回归日志链路。

这一篇在知识体系里的位置 ​

本篇是 docker 排错速查簇的编码与 locale 篇，定位「进程活着、输出也对，就是中文没法看」：同簇运行期故障看 docker 容器卡死速查、docker 容器段错误速查、docker 容器 OOMKilled 速查；构建期语法类问题看 Dockerfile 与 compose 语法错误速查；环境不一致引发的版本类报错看 docker 容器版本不兼容速查。LANG 固化、C.UTF-8 兜底、JVM 编码参数钉死，是中文环境容器化的通用底盘。

一句话总结 ​

docker 中文乱码先在容器内 cat 已知中文文件定分水岭：容器内就乱，查 echo $LANG 与 locale -a 两刀——LANG 为空就 ENV LANG=C.UTF-8（问号型乱码数据已丢，必须防患于未然），Cannot set LC_ALL 是镜像没 locale 数据，装包或直接用 glibc 自带的 C.UTF-8，alpine 的 musl 要装 musl-locales 或在程序层显式 UTF-8；容器内正常而 docker logs 乱是显示端问题，改宿主机终端与 SSH 客户端编码，动容器没用。Java 应用一律 -Dfile.encoding=UTF-8 钉死，别赌容器 locale。把 UTF-8 locale 写进基础镜像模板并在 CI 里卡 LANG 非空，这类乱码基本绝迹。