核心是让关键内容优先渲染：拆分HTML标记非首屏内容、剥离非必要资源、内联关键CSS；Linux需预装中文字体或@font-face内联TTF；weasyprint需压缩图片、降DPI、禁用自动嵌入；puppeteer应waitForFunction检测DOM就绪。
HTML 转 PDF 时首屏内容白屏时间长，怎么压低感知延迟
核心不是“快”，而是让关键内容先出来。多数 html2pdf.js 或 weasyprint 默认整页渲染完才输出 PDF，但用户真正关心的是标题、摘要、图表这些前几屏内容——得优先保障它们的生成路径最短。
- 拆分 HTML：把
<body>中非首屏部分（如“附录”“参考文献”）用data-pdf="defer"标记，转 PDF 前用 JS 动态移除，生成后再合并（适合客户端 JS 渲染场景） - 禁用非必要资源：PDF 渲染器不支持 JS 执行或字体回退，
<link rel="stylesheet">和<script>标签在 PDF 流程中纯属拖慢解析。服务端生成时，用正则或 DOM 操作提前剥离 - 内联关键 CSS：只保留影响首屏布局的样式，用
<style>内联，避免额外 HTTP 请求和解析等待
使用 puppeteer 生成 PDF 时字体模糊、中文乱码怎么办
这不是编码问题，是字体链缺失。puppeteer 底层用 Chromium，而 Linux 容器/无头环境默认不含中文字体，font-family: "PingFang SC", "Microsoft YaHei" 会直接 fallback 到无轮廓的位图字体或空白。
- Linux 环境必须预装字体：Debian/Ubuntu 运行
apt-get install fonts-wqy-zenhei fonts-liberation；Docker 镜像里要写进Dockerfile，不能靠运行时挂载 - CSS 中显式声明
@font-face并 base64 内联字体文件（仅限 TTF，WOFF 不被 Chromium PDF 后端支持），路径必须绝对且可访问 - 设置
pdfOptions.format = 'A4'同时加pdfOptions.printBackground = true，否则背景色、阴影、border-radius 渲染可能异常
weasyprint 生成 PDF 文件体积过大（动辄 10MB+）
根本原因是它把所有图片原样嵌入，且默认不压缩 PNG/JPEG。一张未压缩的截图或 SVG 导出图就能占 2–3MB。
-
前端导出前压缩图片：用
canvas.toBlob(..., 'image/jpeg', 0.7)替代toDataURL，服务端用PIL.Image.save(..., quality=75) - weasyprint 命令行加参数：
--zoom 0.8 --dpi 120，降低渲染分辨率；PDF 本身不依赖高 DPI，120 已足够印刷级清晰度 - 禁用自动嵌入：在 HTML 中给
<img>加loading="lazy"无效，但可用data-pdf-src存原始 URL，Python 中用urllib.request.urlopen下载后本地缩放再写入临时路径，由 weasyprint 引用
PDF 生成失败但控制台没报错，只有空文件或 0 字节
常见于异步资源未就绪就调用了 PDF 生成。puppeteer 的 page.pdf() 不等 DOMContentLoaded，更不等自定义 JS 渲染完成。
立即学习“前端免费学习笔记（深入）”；
- 不用
waitUntil: 'networkidle0'：它只看网络请求，JS 动态插入的内容（如 React/Vue 渲染的表格）可能还没出来 - 改用
page.waitForFunction检查真实 DOM 状态，例如：await page.waitForFunction(() => document.querySelector('#report-header') !== null); - 服务端用 weasyprint 时，确保传入的是完整 HTML 字符串，不是含
<script src="...">的半成品——它不会执行 JS，也不会补全相对路径
