Docker环境下Puppeteer生成PDF时Unicode字符显示异常求助

问题定位 #

基本可以确定是Docker镜像缺少完整的Unicode字体支持——本地环境默认带全量系统字体，能覆盖特殊字符，但node:16基础镜像只装了极简字体，像🌐这类emoji和特殊Unicode字符自然显示异常。

字体安装方案（适配node:16镜像） #

直接安装覆盖主流Unicode字符的字体包，推荐两种靠谱方式：

方式1：安装开源全量字体包 #

在Dockerfile里加以下命令，安装fonts-noto系列字体，能覆盖绝大多数标准Unicode字符和彩色emoji：

# 更新源并安装字体
RUN apt-get update && apt-get install -y --no-install-recommends \
    fonts-noto \
    fonts-noto-color-emoji \
    && rm -rf /var/lib/apt/lists/*

• fonts-noto是Google推出的开源字体，覆盖几乎所有Unicode字符集
• fonts-noto-color-emoji专门解决彩色emoji的显示问题

方式2：挂载本地字体（仅调试用） #

如果想和本地字体效果完全一致，可临时把本地系统字体目录挂载到容器里验证：

docker run -v /usr/share/fonts:/usr/share/fonts -v $(pwd):/app 你的镜像名

注：这种方式只适合调试，生产环境别用，容易出现环境不一致问题。

额外排查点 #

要是装完字体还是不行，检查这几个地方：

• 检查Puppeteer代码配置：确认page.pdf()或page.setFontFamily()里指定的字体，在容器内确实已经安装
• 匹配Chromium版本：Puppeteer 18.0.2对应Chromium 100，确保容器里装的Chromium版本和Puppeteer对应，避免版本不兼容
• 开启背景渲染：在page.pdf()配置里加上{ printBackground: true }，部分特殊字符需要渲染背景才能正常显示

内容的提问来源于stack exchange，提问作者Chris Schaub