wkhtmltopdf是最稳定兼容的HTML转PDF命令行工具，基于WebKit，支持@media print等打印样式；动态页面需用Playwright+Chromium；中文字体和打印CSS是两大关键痛点。
用 wkhtmltopdf 命令行直接转，最稳
浏览器渲染完的 HTML 转 PDF，本质是“截图+排版”，wkhtmltopdf 是目前兼容性最好、控制最细的命令行工具。它底层调用 WebKit，能正确处理 CSS @media print、position: fixed、中文分页等常见坑点。
常见错误现象：phantomjs 已停更，生成 PDF 乱码或不支持 Flex；pdfkit（Node）依赖 wkhtmltopdf 二进制，但默认不带中文字体；浏览器 DevTools 的 “Print to PDF” 手动操作无法自动化。
- Linux/macOS 直接装：
brew install wkhtmltopdf（macOS）或apt install wkhtmltopdf（Ubuntu） - Windows 下务必下载 with QT patch 版本（官网标 “MSVC” 或 “mingw”），否则中文全方块
- 转时显式指定字体路径：
wkhtmltopdf --font-dir "/usr/share/fonts/truetype/wqy" --no-outline input.html output.pdf - 加
--enable-local-file-access才能读取本地file://资源（如本地 CSS/图片）
playwright + Chromium：适合需要 JS 渲染的动态页
如果 HTML 里有 Vue/React 渲染、图表库（ECharts）、滚动加载等内容，wkhtmltopdf 会截到空白页——它不执行 JS。这时候得用真实浏览器引擎。
使用场景：导出后台管理页报表、含 ECharts 的监控看板、带登录态的用户报告。
立即学习“前端免费学习笔记（深入）”；
- Node 环境下装：
npm install playwright，再运行npx playwright install chromium - 关键参数不能少：
await page.pdf({ format: 'A4', printBackground: true, margin: { top: '20px' } })，漏掉printBackground会导致 CSS 背景色丢失 - 务必等 JS 渲染完成：
await page.waitForFunction(() => window.document.readyState === 'complete')，比page.waitForTimeout(2000)更可靠 - 注意内存：每个 PDF 生成都启一个 Chromium 实例，高并发需复用
browser实例，别每次launch()
CSS 里写错 @media print 就白忙活
PDF 导出本质是“打印样式”，所有样式必须通过 @media print 显式声明，或确保默认样式在打印上下文生效。浏览器和 wkhtmltopdf 都遵循这套规则。
容易踩的坑：display: none 写在普通 CSS 里，结果 PDF 里该删的内容还在；background-image 默认不打印；分页断在表格中间，整页空白。
- 强制显示背景：
@media print { * { -webkit-print-color-adjust: exact; } }（WebKit 内核必需） - 避免跨页截断表格：
table { page-break-inside: avoid; }，但注意 Safari 不支持，wkhtmltopdf支持 - 隐藏不需要的元素：
@media print { .no-print, .navbar, .btn { display: none !important; } }，别只靠 JS 移除 DOM - 字号单位用
pt（如font-size: 12pt），别用rem或em，否则缩放异常
中文乱码？90% 是字体没嵌入或路径错
wkhtmltopdf 和 playwright 默认不带中文字体，也不会自动 fallback。报错不会明说“缺字体”，只会表现为方块、空格、或干脆空白。
验证方式：用系统自带的「字符映射表」或 fc-list :lang(zh) 查已安装中文字体名，比如 WenQuanYi Micro Hei、Noto Sans CJK SC。
-
wkhtmltopdf中指定字体：--font-family "Noto Sans CJK SC"，同时确保该字体文件在服务器上存在且可读 - Playwright 中注入字体 CSS：
await page.addStyleTag({ content: '@font-face { font-family: "NotoSans"; src: url("/fonts/NotoSansCJKsc-Regular.woff2"); } body { font-family: "NotoSans"; }' }) - 绝对别用 Windows 字体名如
"Microsoft YaHei"——Linux 容器里肯定没有 - PDF 文件本身不嵌入字体？加参数：
--enable-external-filesystem（wkhtmltopdf）或确保 WOFF2 文件能被 Chromium 加载
真正麻烦的不是转不出来，而是转出来后第 3 页开始错位、表格列宽崩塌、或者某台服务器上好好的，换台机器就全是方块——字体和 CSS 打印上下文这两块，漏查一个就返工。
