自动化生成印刷级PDF的HTML排版和工程落地

WeasyPrint生成的PDF是真正“印刷级”的矢量文档，支持精确分页、字体嵌入、CSS Paged Media标准，而浏览器“另存为PDF”或截图合成仅为位图，放大模糊、无法搜索、样式不可靠。

page.pdf() 生成的 PDF 才算真正“印刷级”，截图合成的只是带文字的图片，放大就糊、搜索不了、字体可能丢——这点必须 upfront 说清。

为什么浏览器“另存为PDF”不能直接用于生产

你试过用 Chrome 打印预览 → “保存为PDF”导出一份幻灯片吗？看起来没问题，但一放大就发现文字边缘发虚，复制粘贴全是乱码，页眉页脚错位，甚至某些 CSS Grid 布局完全塌掉。这不是你的 CSS 写得差，而是浏览器打印模块对 @media print 的支持是“尽力而为”，不是“精确执行”。它会跳过很多现代特性（比如 contain: layout、scroll-snap、自定义字体的 fallback 行为），且不保证 JS 渲染完成后再分页。

• 页面中用了 Reveal.js 或 Slidev？它们依赖 JS 控制当前页状态，打印时很可能只捕获第一页
• 用了 @font-face 加载的思源黑体或 JetBrains Mono？打印 PDF 很可能回退成宋体，且不嵌入字形
• 设置了 break-inside: avoid 防止代码块被截断？Chrome 打印引擎大概率忽略这条规则

Playwright 的 page.pdf() 是怎么绕过这些坑的

它不是调用浏览器的“打印后端”，而是直接复用 Chromium 的 PDF 生成器（同 Blink 内核），在 DOM 和样式树完全稳定后，把 Layout Tree 转成 PDF 指令——这才是真正的矢量输出。关键在于：你得主动控制“什么时候才算稳定”。

• 别只等 page.goto() 完成，要加 await page.waitForFunction('document.readyState === "complete"')
• 如果页面有异步图表（ECharts/Chart.js），得等具体渲染完成：await page.waitForFunction(() => window.myChart?.getOption)
• 对 Reveal.js 类幻灯片，需手动触发到末页并停留：await page.evaluate(() => Reveal.slide(Reveal.getSlides().length - 1))，再等动画结束
• page.pdf() 默认不嵌入字体，必须显式传参：{ printBackground: true, format: 'A4', fontEmbedding: true }

WeasyPrint 适合什么场景，又容易在哪卡住

它不走浏览器，纯 Python 渲染，所以没 JS 执行能力，但对静态 HTML + CSS Paged Media 的支持比任何浏览器都准——尤其适合合同、发票、说明书这类结构固定、无需交互的文档。

立即学习“前端免费学习笔记（深入）”；

• 支持 @page、@page :first、string-set / string() 实现自动目录和页眉联动
• 遇到 position: fixed 页眉？WeasyPrint 会把它重复渲染到每一页，Chrome 打印则常只渲染一次
• 但凡页面里有 fetch() 加载数据、localStorage 读配置、或用 IntersectionObserver 触发懒加载——WeasyPrint 直接报错或空白
• 字体必须本地可访问，url('./fonts/NotoSansCJK.ttc') 路径要绝对或相对于 HTML 文件路径，不能是网络 URL

多列、分页、页码这些“印刷细节”怎么写才真生效

别信网上抄来的 column-count: 3，打印时几乎全失效。真正可靠的是 CSS Grid + break-before 组合。

• 用 display: grid; grid-template-columns: 1fr 1fr 1fr; 替代 column-count，打印引擎识别更稳
• 强制分页别只靠 page-break-after（已废弃），改用 break-after: page + break-inside: avoid
• 页码要用 counter-reset + counter-increment，而不是 JS 插入数字——WeasyPrint 和 page.pdf() 都支持
• 页眉里的当前章节名，靠 string-set: title content(text); + string(title) 实现，这是 CSS Paged Media 标准，不是 hack

复杂点不在工具选型，而在“何时触发 PDF 生成”这个时间点——JS 渲染完成、CSS 动画结束、第三方库就绪，三者必须全部满足，缺一不可。多数失败案例，问题都不在 PDF 库本身，而在等待逻辑漏了一环。