Docker环境下FastAPI调用WeasyPrint导出PDF字体异常问题咨询

Pango版本问题确认 #

你当前使用的Debian 10内置Pango 1.42.0确实是导致sans-serif字体失效的核心原因之一：WeasyPrint 52.5明确要求Pango版本≥1.44.0，该版本起Pango切换为HarfBuzz作为字体渲染引擎，优化了字体别名映射、fallback逻辑，旧版本Pango在容器无预装Helvetica字体的场景下，大概率会出现sans-serif通用字体族匹配失败的问题。

可行解决方案 #

1. 升级Pango版本 #

两种方案二选一即可：

• 更换基础镜像为基于Debian 11（bullseye）的tiangolo/uvicorn-gunicorn-fastapi镜像，Debian 11自带Pango 1.46.x，完全符合WeasyPrint版本要求
• 保留现有Debian 10镜像，新增backports源安装高版本Pango，在Dockerfile的apt命令前添加以下内容：

RUN echo "deb http://deb.debian.org/debian buster-backports main" >> /etc/apt/sources.list.d/backports.list
RUN apt-get update && apt-get install -y -t buster-backports libpango-1.0-0 libpangocairo-1.0-0

2. 修复字体配置 #

你之前复制本地字体无效，大概率是未刷新字体缓存或缺少通用字体fallback配置：

• 安装兼容度最高的默认无衬线字体包，在apt安装命令中添加fonts-dejavu-core
• 复制本地字体到容器的/usr/share/fonts或/root/.local/share/fonts目录后，必须执行fc-cache -fv刷新系统字体缓存
• 可手动添加fontconfig配置强制映射字体，创建/etc/fonts/local.conf写入以下内容：

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
  <alias>
    <family>sans-serif</family>
    <prefer><family>DejaVu Sans</family></prefer>
  </alias>
  <alias>
    <family>Helvetica</family>
    <prefer><family>DejaVu Sans</family></prefer>
  </alias>
</fontconfig>

其他排查点 #

• 可在代码中添加调试逻辑，打印WeasyPrint识别到的字体列表，确认字体已被正确加载：

from weasyprint.fonts import FontConfiguration
font_config = FontConfiguration()
print([f.family for f in font_config.fonts])

• 排除业务HTML样式冲突：使用仅包含基础font-family设置的极简测试HTML生成PDF，验证字体是否生效，排查是否有其他样式覆盖了字体配置
• 检查WeasyPrint运行参数，确认没有指定自定义字体配置文件覆盖了系统默认配置

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