17370845950

Puppeteer 是最稳跨平台 HTML 转 PDF 方案，基于 Chromium 全平台支持、渲染一致，需显式配置 headless: 'new' 和 --no-sandbox；weasyprint 适合 Python 静态报表，不执行 JS；jsPDF+html2canvas 仅适用单页截图，文字不可选、模糊失真。

用 Puppeteer 在 Node.js 里生成 PDF 最稳

跨平台 HTML 转 PDF，Puppeteer 是目前最可靠的选择：它基于 Chromium，Windows/macOS/Linux 全支持，渲染效果和浏览器一致，还能控制页眉页脚、分页、缩放等细节。

常见错误是直接用 puppeteer.launch() 不加参数，在无界面服务器（如 Linux Docker）上会失败。必须显式启用无头模式并跳过沙箱：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: 'new',
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });
  const page = await browser.newPage();
  await page.goto('file:///path/to/your.html', { waitUntil: 'networkidle0' });
  await page.pdf({
    path: 'output.pdf',
    format: 'A4',
    printBackground: true
  });
  await browser.close();
})();

• headless: 'new' 是新版无头模式，兼容性更好；旧写法 headless: true 在较新版本中已弃用
• waitUntil: 'networkidle0' 确保所有资源加载完成，比 domcontentloaded 更稳妥
• 本地 HTML 文件要用 file:// 协议，不能直接传相对路径字符串
• Docker 部署时需安装系统依赖：libx11-dev libxext-dev libxfixes-dev libnss3-dev libgconf-2-4-dev libasound2-dev libatk1.0-dev libgtk-3-dev

Python 用户优先选 weasyprint 而非 pdfkit

pdfkit 底层调用 wkhtmltopdf，跨平台安装麻烦（尤其 macOS M1/M2、Windows 新版），且对 CSS Grid/Flex 支持差；weasyprint 纯 Python 实现，依赖少，CSS3 支持更实诚，适合报表类静态 HTML。

注意它不执行 JavaScript，所以含 document.write 或动态渲染的内容会空白：

from weasyprint import HTML

HTML('report.html').write_pdf('report.pdf', stylesheets=['style.css'])

• 字体问题最常踩坑：Linux/macOS 默认无中文字体，需在 CSS 中显式指定 @font-face 并确保路径可读
• 不支持 position: fixed 用于页眉页脚（它靠 @page 规则实现），别照搬浏览器写法
• 表格跨页断裂时，加 table { break-inside: avoid; } 可缓解，但不能完全避免
• 性能比 Puppeteer 慢，千行以上 HTML 建议加 subprocess 异步调用或换方案

前端直接转 PDF？只适合简单场景

浏览器里用 jsPDF + html2canvas 是伪“HTML 转 PDF”——本质是把 DOM 截图再塞进 PDF，结果模糊、不支持真分页、无法复制文本、打印缩放失真。

仅适用于导出一页以内、无交互、无复杂布局的快照（如二维码卡片、单张数据看板）：

html2canvas(document.body).then(canvas => {
  const imgData = canvas.toDataURL('image/png');
  const pdf = new jsPDF();
  pdf.addImage(imgData, 'PNG', 0, 0);
  pdf.save('page.pdf');
});

• html2canvas 对 transform、filter、跨域图片支持弱，经常白屏或错位
• 生成的 PDF 文件体积大（存的是 PNG），文字不可选，SEO 和无障碍全丢
• 移动端 Safari 限制更多，html2canvas 可能直接报 SecurityError
• 别试图用它处理含 iframe、Shadow DOM 或 Web

  

  Component 的页面

云服务 or CLI 工具？看你的可控性需求

如果不想维护环境，DocRaptor、PDFShift 这类 API 确实省事，但 HTML 传到第三方，敏感数据有风险；wkhtmltopdf CLI 虽老，但在 CI/CD 里稳定，只是 Windows 上得手动装二进制、macOS 上得用 brew install wkhtmltopdf。

• wkhtmltopdf 的 --enable-local-file-access 参数必须加，否则 file:// 引用的 CSS/JS 全 404
• 它不支持 CSS contain、aspect-ratio 等新特性，查文档前先确认版本（wkhtmltopdf --version）
• 云 API 返回的 PDF 若出现字体缺失，不是你 CSS 写错了，是服务端没装对应字体——得改用 base64 内联字体
• CI 流程中若用 Docker，推荐 alpeware/chrome-headless-trunk 镜像而非自己配 Puppeteer，省去一堆依赖折腾

真正难的不是选哪个工具，而是 HTML 本身是否为打印而设计：媒体查询没写 @media print、用了太多绝对定位、忘了设 body { margin: 0; }，再好的转换器也救不回错乱的 PDF。