wkhtmltopdf 是兼容性最好、行为最可预测的pdf生成方案，适用于无复杂js渲染或登录态的html；需注意file://路径、--enable-local-file-access、utf-8编码、中文字体及css分页控制。
用 wkhtmltopdf 命令行直接转，最稳
多数人卡在“选哪个工具”，其实只要不涉及复杂 JS 渲染或登录态，wkhtmltopdf 是目前兼容性最好、行为最可预测的方案。它本质是把 WebKit 渲染引擎封装成命令行工具，不是靠 JS 模拟渲染，所以 HTML 里用 float 布局、@media print 样式都能照常生效。
常见错误现象：wkhtmltopdf 报 Exit with code 1 due to network error，大概率是本地路径没加 file:// 前缀，或者 HTML 里引用了远程 CSS/JS 但网络不通。
- Windows 下确保路径用正斜杠或双反斜杠：
wkhtmltopdf file:///C:/report.html out.pdf - Linux/macOS 要加
file://：wkhtmltopdf file:///home/user/page.html out.pdf - 如果 HTML 含相对路径资源（如
./style.css），必须用--enable-local-file-access参数，否则资源加载失败 - 中文乱码？加
--encoding utf-8 --outline-depth 2，并确认系统已安装中文字体（如 Debian 上装fonts-wqy-zenhei）
用 pdfkit（Python）时别直接传字符串
pdfkit 是 wkhtmltopdf 的 Python 封装，方便集成进脚本，但很多人直接传 HTML 字符串导致样式丢失或编码错乱——它默认按 ASCII 解析，不自动识别 UTF-8。
使用场景：需要动态生成 HTML 再转 PDF，比如报表导出、邮件模板预览。
立即学习“前端免费学习笔记（深入）”；
- 永远用
open(..., encoding='utf-8')读文件，再传给pdfkit.from_file()，别用.read()后拼字符串 - 如果必须从字符串生成，务必加
configuration=pdfkit.configuration(encoding='UTF-8') - 注意
pdfkit不处理fetch()或XMLHttpRequest，JS 渲染的内容不会出现在 PDF 里 - 超长表格截断？加 CSS：
table { page-break-inside: avoid; }，配合--page-size A4 --margin-top 10
浏览器 DevTools 的 “Print to PDF” 功能不可靠
Chrome / Edge 地址栏点“打印 → 另存为 PDF”，看着方便，但实际用于自动化或批量处理时问题集中：字体嵌入失败、CSS @media screen 规则被忽略、页眉页脚无法关闭、JavaScript 执行时机不可控。
典型错误现象：PDF 里显示“Loading...”，或按钮文字变成方块，或分页完全错乱。
- 仅适合人工临时查看，不能写进 CI/CD 流程或定时任务
- 若真要用，必须在 HTML 中显式定义
@media print，且禁用所有动画和过渡效果 - 绝对不要依赖
window.print()触发——它不返回 Promise，无法监听完成，也无法捕获失败
遇到 ReferenceError: window is not defined 别硬改源码
这是在 Node.js 环境下用某些前端库（比如 chart.js、highlight.js）生成 HTML 后转 PDF 时的高频报错。根本原因是这些库默认假设有 window 对象，而 wkhtmltopdf 渲染时虽有 DOM，但部分全局对象不完整。
性能影响：强行 polyfill window 可能导致 PDF 渲染变慢甚至崩溃，尤其含大量 Canvas 图表时。
- 优先改生成逻辑：服务端用
canvas+chart.jsnode 版本直接画图，输出 PNG 再插入 HTML - 避免在 HTML 中内联执行 JS 初始化代码；把图表数据用 JSON 注入，等 PDF 渲染完再由客户端 JS 补充（但 PDF 里不会执行）
- 如果必须保留 JS 渲染，改用
puppeteer，但它启动 Chromium 实例开销大，不适合高并发
真正难搞的是带身份校验、单页应用路由、或依赖 Service Worker 的 HTML —— 这类页面不是“转 PDF”的问题，而是“先让它正确渲染出来”的问题。得先解决渲染上下文，再谈格式转换。
