17370845950

核心是让关键内容优先渲染：拆分HTML标记非首屏内容、剥离非必要资源、内联关键CSS；Linux需预装中文字体或@font-face内联TTF；weasyprint需压缩图片、降DPI、禁用自动嵌入；puppeteer应waitForFunction检测DOM就绪。

HTML 转 PDF 时首屏内容白屏时间长，怎么压低感知延迟

核心不是“快”，而是让关键内容先出来。多数 html2pdf.js 或 weasyprint 默认整页渲染完才输出 PDF，但用户真正关心的是标题、摘要、图表这些前几屏内容——得优先保障它们的生成路径最短。

• 拆分 HTML：把 中非首屏部分（如“附录”“参考文献”）用 data-pdf="defer" 标记，转 PDF 前用 JS 动态移除，生成后再合并（适合客户端 JS 渲染场景）
• 禁用非必要资源：PDF 渲染器不支持 JS 执行或字体回退， 和 标签在 PDF 流程中纯属拖慢解析。服务端生成时，用正则或 DOM 操作提前剥离
• 内联关键 CSS：只保留影响首屏布局的样式，用 内联，避免额外 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 中给 加 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 字符串，不是含 的半成品——它不会执行 JS，也不会补全相对路径

实际中最容易被忽略的，是 PDF 渲染上下文与浏览器的差异：没有 localStorage、没有 window.matchMedia、CSS @media print 规则会被应用但 @media screen 不会。任何依赖运行时环境判断的逻辑，在 PDF 生成阶段都会静默失效。