html怎么转换成pdf_html转PDF文件格式技巧【详解】

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 打印上下文这两块，漏查一个就返工。