预览时应使用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 中加入
<meta name="viewport" content="width=device-width, initial-scale=1">，否则打印预览可能缩放异常 - 避免使用
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; }可缓解
