问题复现：为什么你的 n8n 面板全是“豆腐块”？
笔者在 N8N大学 社区里潜水时，发现很多新手在 Docker 部署 n8n 后，都会遇到一个极其搞心态的问题：原本应该显示的中文内容，全部变成了方框（俗称“豆腐块”）或者乱码。
这种情况通常发生在以下场景：
- 你使用 Docker 部署了 n8n，宿主机是 Linux (Ubuntu/CentOS)。
- 你在 HTML 节点中渲染中文邮件模板。
- 你使用 Read Binary File 和 PDF 节点生成中文 PDF 报表。
- 你在自定义 JS 代码中生成带中文的图片验证码。
控制台里可能不会报错，但生成的文件或界面显示就是一团糟。这背后其实不是 n8n 的锅，而是 Docker 容器内“赤手空拳”，缺少了处理中文字符集的字体库环境。
原因分析：Docker 的“极简主义”陷阱
为什么会出现乱码？用大白话讲，n8n 底层依赖 Puppeteer（浏览器截图/打印）或 ImageMagick 等工具来处理图形化内容。这些工具在渲染文字时，需要去系统里找对应的字体文件（比如 .ttf 或 .otf）。
然而，官方的 Docker 镜像为了保持体积极小，默认只安装了基础的英文字体。当中文字符传入时，系统找不到对应的中文字体文件，渲染引擎就会降级处理，最终显示为一个个空白方框。
解决方案一：挂载宿主机字体（最快修复）
如果你不想重建镜像，只想快速修复现有的容器，最简单的办法就是把宿主机的字体目录映射到容器内。前提是你的宿主机得有中文字体。
操作步骤：
- 找到宿主机字体： 在 Ubuntu/Debian 上，通常
/usr/share/fonts目录下会有字体。如果没有，先安装：sudo apt-get install fonts-wqy-microhei（安装文泉驿微米黑）。 - 修改 Docker 运行命令： 在你的
docker run命令或docker-compose.yml中，添加-v挂载参数。
示例代码如下：
docker run -d
--name n8n
-p 5678:5678
-v ~/.n8n:/home/node/.n8n
-v /usr/share/fonts:/usr/share/fonts:ro # <-- 这一行是关键
docker.n8n.io/n8nio/n8n重启容器后，再次测试中文渲染，90% 的情况下乱码问题直接消失。
解决方案二：自定义 Dockerfile（彻底根治）
如果你是强迫症患者，或者需要特定的商业字体（比如做海报），挂载宿主机字体可能不够稳定。N8N大学 推荐构建自己的定制镜像，一劳永逸。
操作步骤：
- 创建 Dockerfile： 在任意目录新建一个名为
Dockerfile的文件。 - 编写构建指令： 我们基于官方镜像，补充安装中文字体的步骤。
FROM docker.n8n.io/n8nio/n8n
# 切换到 root 用户以安装软件包
USER root
# 安装中文字体（以文泉驿为例，你也可以上传自己的字体文件）
RUN apt-get update &&
apt-get install -y fonts-wqy-microhei &&
# 清理缓存
apt-get clean &&
rm -rf /var/lib/apt/lists/*
# 刷新字体缓存，让系统识别新字体
RUN fc-cache -fv
# 切换回 n8n 默认用户
USER node在 Dockerfile 所在目录执行：
docker build -t my-n8n:latest .
docker run -d --name n8n-fixed -p 5678:5678 my-n8n:latest避坑指南：Puppeteer 的特殊配置
在解决乱码问题时，很多用户反馈挂载字体后依然无效。这通常是因为 Puppeteer（n8n 内部用于生成 PDF/截图的浏览器引擎）没有正确指向字体路径。
避坑点： 如果你使用的是 HTML to PDF 或 HTML to Image 节点，仅仅安装字体可能不够。
笔者建议： 在这些节点的参数中，如果支持自定义 CSS，请务必显式指定字体家族。例如：
body {
font-family: "WenQuanYi Micro Hei", "Microsoft YaHei", sans-serif !important;
}此外，如果你的 Docker 环境是 Alpine Linux 版本（虽然 n8n 官方基于 Debian，但有些用户自己改了），Alpine 的字体处理机制完全不同，极其容易踩坑。强烈建议坚持使用基于 Debian 的基础镜像，省去折腾字体配置文件的麻烦。
FAQ 常见问题
Q1: 我只是想在 n8n 的 Web UI 里显示中文，需要这么麻烦吗？
A: 通常不需要。n8n 的 Web 界面本身支持 UTF-8 编码，如果你是在 Set 节点或 Code 节点处理数据乱码，通常是因为你的数据库或源数据本身编码不对，或者没有在 HTTP 响应头中正确设置 Content-Type: text/html; charset=utf-8。上述方案主要针对“图形生成”和“文件导出”场景。
Q2: 为什么我安装了字体，生成的 PDF 中文还是方框？
A: 这种情况通常是因为字体缓存没有刷新。在 Dockerfile 中执行 fc-cache -fv 非常关键。如果依然无效，请检查容器内 /usr/share/fonts 目录下是否真的有你想要的字体文件，并且权限是否为 644。
Q3: 这种修复方法会影响 n8n 的升级吗？
A: 如果你使用的是“解决方案二”（自定义 Dockerfile），每次 n8n 官方发布新版本时，你需要重新构建镜像。为了方便维护，建议将 Dockerfile 放入 Git 仓库管理，或者使用 Watchtower 等工具配合脚本自动重建。
总结与资源
解决 n8n 中文乱码，本质上是补齐 Docker 容器内缺失的字体环境。对于快速修复，直接挂载宿主机字体目录即可；为了长期稳定运行，建议使用 Dockerfile 构建定制镜像。
在 N8N大学，我们始终认为细节决定成败。希望这篇指南能帮你彻底解决“豆腐块”烦恼。如果你在实操中遇到其他报错，欢迎在评论区留言，笔者会第一时间回复。
