Docker容器内使用wkhtmltopdf生成PDF时页眉页脚不显示问题求助

核心原因 #

你当前通过apt直接安装的wkhtmltopdf是Debian官方源提供的精简版本，未携带QT全功能补丁，默认缺失页眉页脚渲染、自定义页边距、无GUI环境运行等核心功能。你本地调试环境安装的一般是带QT补丁的全功能版本，所以功能正常，容器内的精简版本无法支持对应配置，这就是问题的根本原因。

修复步骤 #

替换Dockerfile中wkhtmltopdf的安装逻辑，安装官方预编译的带QT补丁的全功能版本，修改后的对应部分如下：

# 替换原有的RUN apt-get install wkhtmltopdf -y 部分
RUN apt-get update && \
    # 安装wkhtmltopdf运行依赖+常用字体（避免页眉页脚缺字不显示）
    apt-get install -y --no-install-recommends \
        libxrender1 \
        libfontconfig1 \
        libjpeg62-turbo \
        fonts-wqy-zenhei \
        fonts-dejavu \
        wget \
    && wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.bullseye_amd64.deb \
    && dpkg -i wkhtmltox_0.12.6.1-2.bullseye_amd64.deb \
    # 清理缓存减少镜像体积
    && apt-get purge -y wget \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/* wkhtmltox_0.12.6.1-2.bullseye_amd64.deb

验证方法 #

镜像构建完成后进入容器执行命令：

wkhtmltopdf --version

输出结果中包含with patched qt则说明安装正确，重新生成PDF即可正常显示页眉页脚。

额外注意事项 #

如果你的页眉页脚使用了特殊自定义字体，需要将对应的字体文件拷贝到容器的/usr/share/fonts目录下，并执行fc-cache -fv刷新字体缓存，避免字体缺失导致内容不显示。

内容的提问来源于stack exchange，提问作者Folded Panda