wkhtmltopdf 是基于 WebKit 的原生命令行工具，解析快、一致性高，适合服务端批量转换；需加 --encoding utf-8、--enable-local-file-access、--print-media-type 等参数解决乱码、资源加载和打印样式问题，JS 渲染内容须预处理为静态 HTML。
用 wkhtmltopdf 命令行直接转，最稳
浏览器渲染 HTML 再截图或打印 PDF 的方式（比如 Puppeteer）容易因 JS 加载时机、字体缺失、页面跳动出错；wkhtmltopdf 是基于 WebKit 的原生命令行工具，不启浏览器，解析快、一致性高，适合批量或服务端转换。
- 安装后直接运行：
wkhtmltopdf input.html output.pdf - 中文乱码？加参数：
--encoding utf-8 --no-outline --enable-local-file-access - 页面内容被截断？默认 A4 宽度太窄，加：
--page-width 1200 --page-height 8000（单位 px） - 本地图片/样式不加载？必须加
--enable-local-file-access，否则报QNetworkAccessManager::OperationCanceledError
iframe 或动态渲染的 HTML 转 PDF 失败怎么办
wkhtmltopdf 不执行 JS，遇到 document.write、Vue 渲染、异步请求填充内容，PDF 里就是空的或只有骨架。
- 先用 Puppeteer 等工具预渲染成静态 HTML：
await page.setContent(html, { waitUntil: 'networkidle0' });，再喂给wkhtmltopdf - 不要依赖
window.onload或setTimeout延迟生成——wkhtmltopdf不认这些 - 若必须用 JS 渲染 PDF，改用
puppeteer.launch({ headless: true })+page.pdf()，但注意内存和超时控制
CSS 打印样式写不对，PDF 排版全乱
浏览器“另存为 PDF”和 wkhtmltopdf 都走 CSS @media print 规则，但默认不启用，且对 position: fixed、transform、Flex/Grid 支持有限。
- 强制启用打印样式：
--print-media-type参数必须加，否则@media print被忽略 - 避免
position: fixed页眉页脚——它在 PDF 里会重复出现在每一页顶部，用--header-html和--footer-html单独传 - 表格跨页断裂？加 CSS：
table { break-inside: avoid; }，但注意旧版wkhtmltopdf（0.12.x）不支持，需 0.13.0+
Python 脚本调用 wkhtmltopdf 报错：找不到命令或权限拒绝
不是代码问题，是环境没配好。很多 Python 包（如 pdfkit）只是 wkhtmltopdf 的封装，底层仍依赖系统命令。
立即学习“前端免费学习笔记（深入）”；
- 确认已安装：
wkhtmltopdf --version能输出版本号；macOS 用brew install wkhtmltopdf，Ubuntu 用apt install wkhtmltopdf - Python 中指定路径：
config = pdfkit.configuration(wkhtmltopdf='/usr/local/bin/wkhtmltopdf') - Linux 容器里报
QXcbConnection: Could not connect to display？加--xvfb或换用无头模式：wkhtmltopdf --use-xserver ...（不推荐），更稳妥是升级到wkhtmltopdf0.12.6+ 并确保libxrender1、libfontconfig1已装
base64 图片路径错、file:// 协议限制、CSS 优先级冲突这几个坑混在一起排查。 
