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全是no，说明字体没嵌入，需升级到 v0.12.6+ 并加--load-error-handling ignore配合@font-face - weasyprint 默认嵌入，但若用
font-family: "Noto Sans CJK SC"却没提前注册该字体文件，它会 fallback 到无嵌入的替代字体
pdffonts 输出和实际 TTF 文件路径。 
