html转pdf字体缺失咋补全_补字体转pdf法【补救】

星夢妙者 2026-01-20 00:00:00 次阅读

HTML转PDF中文显示方块的本质是字体未嵌入或未正确声明；需为wkhtmltopdf配置--font-dir或@font-face，为weasyprint显式注册字体路径，并用pdffonts验证emb列确认嵌入。

HTML 转 PDF 时中文显示为方块，本质是字体未嵌入或未声明

不是所有 PDF 工具都默认支持中文字体。wkhtmltopdf、weasyprint、pdfkit 这类工具依赖系统字体或显式指定的字体文件，一旦 HTML 中用了 font-family: "Microsoft YaHei", sans-serif，而生成环境（如 Linux 服务器）没装雅黑，就必然出方块。

wkhtmltopdf 必须用 `--font-dir` 或 `@font-face` 加载中文字体

Linux 下默认无中文字体，不能靠 font-family 名字碰运气。必须让工具“看见”字体文件：

wkhtmltopdf 启动时加 --font-dir /path/to/fonts，并确保该目录下有 simhei.ttf、msyh.ttc 等真实字体文件
更稳妥的是在 HTML 中用 @font-face 内联声明（路径需可被 wkhtmltopdf 访问，推荐用绝对路径或 base64）
避免用 font-family: "PingFang SC" 这类 macOS 专属字体名，跨平台必挂

@font-face {
  font-family: "SimHei";
  src: url("/usr/share/fonts/truetype/simhei.ttf") format("truetype");
}
body { font-family: "SimHei", sans-serif; }

weasyprint 需在 Python 里注册字体路径，不能只靠 CSS

weasyprint 不会自动扫描系统字体，必须显式告诉它字体在哪：

调用前设置环境变量：WEASYPRINT_FONTS=/usr/share/fonts/truetype/dejavu
或在代码里注册：from weasyprint import FontConfiguration; font_config = FontConfiguration(); font_config.add_font(...)
若用 Docker，记得 COPY 字体文件进镜像，并挂载到对应路径
注意：TTF 文件权限要是 644，否则 weasyprint 会静默跳过

PDF 输出后仍缺字？检查字体是否真正嵌入而非仅引用

有些工具（尤其旧版 wkhtmltopdf）默认不嵌入字体，只做“字体替换”，导致 PDF 在其他设备打开仍乱码：

对 wkhtmltopdf，加参数 --no-outline --enable-local-file-access --encoding utf-8 是基础，但关键要确认是否嵌入：用 pdffonts output.pdf 查看输出里有没有 yes 标记的 emb 列
如果 emb 全是 n o，说明字体没嵌入，需升级到 v0.12.6+ 并加 --load-error-handling ignore 配合 @font-face
weasyprint 默认嵌入，但若用 font-family: "Noto Sans CJK SC" 却没提前注册该字体文件，它会 fallback 到无嵌入的替代字体