17370845950

预览时应使用Chrome/Edge打印预览（Ctrl+P→另存为PDF）模拟PDF输出，因其最贴近puppeteer/wkhtmltopdf；需加viewport meta、避免fixed/transform布局、用puppeteer显式设A4尺寸与页边距，并处理异步资源。

HTML 预览时就该模拟 PDF 渲染效果

直接在浏览器里打开 index.html 看到的样式，和最终转成 PDF 的结果常常不一致——比如分页错乱、字体缺失、@media print 未生效、CSS Flex/Grid 布局塌陷。预览阶段就要用「接近 PDF 输出引擎」的方式看，而不是依赖普通浏览器渲染。

• Chrome / Edge 的打印预览（Ctrl+P → 选择“另存为 PDF”）最贴近 puppeteer 或 wkhtmltopdf 的输出逻辑，优先用它验证布局和分页
• 务必在 HTML 中加入 ，否则打印预览可能缩放异常
• 避免使用 position: fixed 或 transform 做关键布局，PDF 引擎对这些支持不稳定，预览时就能发现内容消失或错位

用 puppeteer 在 Node.js 中实现「预览即所见」的 PDF 导出

puppeteer 是目前最可控的 HTML→PDF 方案，它复用 Chromium 内核，所以你在打印预览里看到的，基本就是 page.pdf() 输出的。

• 安装：npm install puppeteer（会自动下载 Chromium，首次运行较慢）
• 关键参数必须显式设置，否则默认 A4 尺寸下内容会被压缩或截断：

  await page.pdf({
    format: 'A4',
    printBackground: true,
    margin: { top: '20px', right: '20px', bottom: '20px', left: '20px' },
    preferCSSPageSize: false // 必须设为 false，否则忽略 format 和 margin
  });

• 如果页面含异步资源（如图表、远程图片），需加 await page.waitForNetworkIdle({ timeout: 5000 });，否则 PDF 里留白或占位符

wkhtmltopdf 的兼容性陷阱与替代建议

wkhtmltopdf 轻量但老旧，不支持现代 CSS（如 grid、aspect-ratio），且在 macOS M 系列或新 Linux 发行版上常因 Qt 版本问题崩溃。错误信息类似：QXcbConnection: Could not connect to display。

• 若必须用它，启动时加 --no-xserver-clipboards --enable-local-file-access 参数解决常见权限和路径问题
• 字体渲染差异大：系统字体需提前用 @font-face 显式加载，不能依赖 font-family: "Helvetica" 这类通用名
• 更稳妥的替代是 playwright（API 类似 puppeteer，但更新快、多浏览器支持更好）或服务化方案如 pdfshift（适合无服务端环境）

CSS 中影响 PDF 输出的关键规则要单独写

PDF 引擎只认部分 CSS，且对 @media print 解析比浏览器更严格。不要把屏幕样式和打印样式混写在一个选择器里。

• 强制分页用 page-break-before: always 或 break-before: page（后者是新标准，puppeteer 已支持）
• 隐藏非打印元素：@media print { .nav, .btn { display: none; } }，别用 visibility: hidden，它仍占空间
• 表格跨页断裂很常见，加 table { break-inside: avoid; } 和 tr { break-inside: avoid; } 可缓

  

  解

实际 PDF 质量取决于预览阶段是否暴露了分页、字体、尺寸问题。很多“转 PDF 失败”本质是 HTML 结构没为打印场景做适配——不是工具不行，是没在预览环节盯住细节。