最可靠方案是 html-pdf-cli（基于 Puppeteer）：支持 A4、页边距等参数，自动等待 DOM 加载，需本地 HTTP 服务或 --no-sandbox；wkhtmltopdf 仅适用于简单静态页且需 ≥0.12.6 版本；weasyprint 适合无 Node 环境，纯 Python 实现但不执行 JS。
用 puppeteer 命令行直接转 HTML 为 PDF 最可靠
浏览器渲染引擎生成的 PDF 质量最高，puppeteer（基于 Chromium）是目前命令行下最稳定的选择。它能正确处理 CSS @media print、JavaScript 渲染、字体嵌入和分页，远胜于老旧的 wkhtmltopdf（已停止维护，不支持现代 CSS）。
安装后无需写 JS 脚本也能快速转换：
npx puppeteer render --pdf output.pdf input.html
但注意：puppeteer 默认不带 render CLI；需额外安装封装工具或自己写一行脚本。更通用的做法是用轻量封装 html-pdf-cli（底层仍是 Puppeteer）：
npm install -g html-pdf-cli html-pdf-cli input.html output.pdf
- 支持传入
--viewport-width、--format（如A4）、--margin-top等参数 - 自动等待
DOMContentLoaded，若页面有异步数据，需加--wait-for-selector指定加载完成标志 - 不支持本地
file://协议直读（会触发 CORS），必须起一个本地 HTTP 服务或用--no-sandbox启动 Chromium（仅限可信环境）
wkhtmltopdf 还能用吗？兼容性与风险点
可以，但只建议用于简单静态页面，且必须确认版本 ≥ 0.12.6（旧版对 Flex/Grid 支持极差）。常见报错如 QPainter::begin: Paint device returned engine == 0, type: 2，本质是缺少系统依赖（如 Ubuntu 需装 libxrender1 libfontconfig1 libx11-xcb1）。
立即学习“前端免费学习笔记（深入）”；
典型命令：
wkhtmltopdf --page-size A4 --margin-top 20 --margin-bottom 20 input.html output.pdf
-
--enable-local-file-access必须加，否则无法加载本地 CSS/JS -
--javascript-delay 2000可缓解 JS 渲染未完成问题，但不如 Puppeteer 的waitFor精确 - Windows 下中文乱码？需指定系统字体路径：
--outline-depth 3 --font-family "SimSun"，且确保该字体已安装
Python 用户优先用 weasyprint 而非 pdfkit
pdfkit 只是 wkhtmltopdf 的 Python 封装，没解决底层缺陷；而 weasyprint 是纯 Python 实现，支持 CSS3 大部分特性（包括 @page、break-before），且无二进制依赖。
pip install weasyprint python -m weasyprint input.html output.pdf
- 默认使用系统字体，中文需显式指定：
weasyprint input.html output.pdf --font-config /path/to/fonts.conf - 不执行 JavaScript，适合内容静态、样式复杂的报表类 HTML
- 性能比 Puppeteer 慢，但内存占用低，适合批量转简单页面
为什么不能直接用 chrome --headless --print-to-pdf？
Chrome 官方确实支持该参数，但实际限制极多：
- 必须传完整 URL（
http://或https://），不接受file://路径 - PDF 选项只能通过 JSON 文件传入（如
--print-to-pdf=output.pdf --print-to-pdf-no-header --virtual-time-budget=5000不生效） - 无法控制分页符位置，
@media print中的break-after常被忽略 - Chrome 110+ 移除了部分 headless 打印参数，文档已标记为“deprecated”
真正稳定的方案仍是封装好的工具链，而非裸调 Chrome 参数。如果已有 Node.js 环境，html-pdf-cli 是最省心的起点；若服务器受限（如无 GUI、无 Node），weasyprint 更可控。
