HTML转PDF格式详解与使用技巧

本文深入解析HTML转PDF过程中常见的样式丢失、中文字体异常、动态内容渲染空白、PDF体积过大及文字不可选等核心痛点，直击wkhtmltopdf、Puppeteer和客户端jsPDF等主流方案在媒体查询忽略、相对单位失效、字体未嵌入、JS执行时机错位、图片base64滥用及分页机制不兼容等底层原因，并提供可落地的参数配置、CSS重写规范、字体加载策略、渲染等待机制和轻量压缩技巧，助你稳定输出专业、轻量、可编辑、跨平台兼容的高质量PDF文档。

HTML 转 PDF 时样式丢失怎么办

直接用 wkhtmltopdf 或浏览器 printToPDF API 渲染 HTML，90% 的样式问题出在「媒体查询」和「相对单位」上。默认情况下，这些工具会忽略 @media print 外的 CSS，且不渲染 vh/vmin 等视口单位——它们在无窗口上下文里没意义。

• 强制启用所有样式：加 --no-stop-slow-scripts 和 --enable-local-file-access 参数（wkhtmltopdf）
• 把 rem/em 换成 pt 或 mm：PDF 是物理尺寸优先，16px ≈ 12pt，建议根字体设为 12pt
• 禁用 @media screen，显式写 @media print，并在其中重置 body { margin: 0; } 防白边
• 背景图默认不打印，需加 -webkit-print-color-adjust: exact; 或 print-color-adjust: exact;

中文断行与字体嵌入失败怎么处理

Linux/macOS 下 wkhtmltopdf 默认不带中文字体，Windows 自带宋体但不嵌入，导致导出 PDF 里中文显示为方块或被替换成黑体——这不是编码问题，是字体资源缺失。

• 确认系统已安装字体：Linux 用 fc-list :lang=zh 查看，macOS 检查 /Library/Fonts/，Windows 查 C:\Windows\Fonts\
• HTML 中用 @font-face 显式加载本地字体文件（如 simhei.ttf），并设 font-family: "SimHei"，避免依赖系统回退
• wkhtmltopdf 启动时加 --font-dir /path/to/fonts，并确保路径可读；若用 Docker，需挂载字体目录且在容器内执行 fc-cache -fv
• 导出后用 pdfinfo -meta your.pdf 检查是否含嵌入字体，字段 Fonts: 下应有 embedded 标记

动态内容（Vue/React）转 PDF 渲染空白或未加载

静态 HTML 转 PDF 没问题，但 SPA 页面常因 JS 未执行完、路由懒加载未触发、或 SSR 未启用而输出空壳。这不是 PDF 工具的问题，是渲染时机没对齐。

• 服务端生成：用 Puppeteer 启动真实 Chromium 实例，等 page.waitForFunction(() => window.__APP_READY__)（自己设个全局标记）再截图
• 避免依赖 window.location 或 localStorage——Puppeteer 默认禁用部分 API，需显式启用 --disable-features=IsolateOrigins
• 若用 html2canvas + jsPDF 客户端方案，注意 canvas 不支持跨域图片、transform 层级错乱、以及 position: fixed 元素偏移
• 分页控制别靠 CSS page-break-after：它在 canvas 截图里完全失效，改用绝对定位 + height: 297mm（A4）手动切区域

PDF 文件体积过大或文字无法复制

导出后 PDF 达几十 MB，或者打开只能看不能选文字，大概率是「位图替代矢量」或「字体未嵌入+未回退」。关键不是压缩，而是源头渲染方式。

• 禁用 --image-quality 100（wkhtmltopdf 默认就是 94，设太高反而增大体积）
• 关闭图片转 base64：HTML 中不要用 data:image/...，改用 file:// 或 HTTP 路径，并加 --enable-local-file-access
• 文字不可选 = 字体未嵌入或用了 webfont 但未声明 font-display: swap 导致 fallback 失败；检查生成 PDF 的字体列表是否含 Subtype: Type1 或 TrueType
• 用 qpdf --stream-data=compress input.pdf output.pdf 压缩流数据，比 Ghostscript 更轻量且不破坏文字可选性

最麻烦的其实是分页逻辑和页眉页脚的定位偏移——CSS 的 @page 在不同引擎支持度差异极大，wkhtmltopdf 不支持 :first 伪类，Puppeteer 又不支持 running() 函数。真要稳定输出，得放弃纯 CSS 分页，改用 JS 计算内容高度后手动插入分页符节点。

理论要掌握，实操不能落！以上关于《HTML转PDF格式详解与使用技巧》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！