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，省去一堆依赖折腾
@media print、用了太多绝对定位、忘了设 body { margin: 0; }，再好的转换器也救不回错乱的 PDF。 
