HTML转PDF会拖慢转换速度吗？【经验分享】

HTML转PDF本身并不慢，真正拖慢速度的是浏览器引擎渲染阶段——包括CSS/JS加载、远程字体请求、SPA内容异步挂载及复杂排版绘制；实践中需摒弃networkidle2等通用等待策略，改用精准的waitForFunction打点机制，禁用不可靠的setTimeout，合理配置字体嵌入与本地文件访问权限，并警惕wkhtmltopdf脚本中断风险和跨平台（如微信内置浏览器）的兼容性陷阱，才能稳定高效生成高质量PDF。

HTML 转 PDF 本身不慢，慢的是渲染阶段

直接用 wkhtmltopdf 或 Puppeteer 调用 Chromium 渲染 HTML 成 PDF，核心耗时不在“转换”这个动作，而在浏览器引擎加载 CSS、执行 JS、排版布局、绘制页面的过程。你看到的“卡住几秒”，基本都是在等 document.readyState === 'complete' 或资源加载完毕。

• 含大量 background-image、@font-face 或远程字体（如 Google Fonts）的页面，会因网络请求阻塞渲染
• 未加 media="print" 的样式表仍会被加载并参与计算，哪怕最终不显示
• JS 框架（Vue/React）若未等数据挂载完成就截屏，PDF 里可能留白或显示 loading

用 Puppeteer 生成 PDF 时，关键不是 waitUntil，而是 waitForFunction

page.goto(url, { waitUntil: 'networkidle2' }) 看似稳妥，但对 SPA 页面常失效——因为路由切换不触发新导航，networkidle2 很早就满足，而真实内容还没渲染出来。

• 改用 page.waitForFunction('window.__DATA_READY__ === true')，在页面 JS 中手动置位更可靠
• 避免用 setTimeout 等固定毫秒数，不同服务器 CPU 负载下差异极大
• 务必加超时： waitForFunction(..., { timeout: 15000 })，否则进程可能永久挂起

wkhtmltopdf 的 --no-stop-slow-scripts 是个危险开关

当 HTML 含复杂 JS（比如 ECharts 初始化、Canvas 绘图），wkhtmltopdf 默认会在 10 秒后中断脚本执行，导致 PDF 截断或图表空白。启用 --no-stop-slow-scripts 能缓解，但代价是：一旦 JS 死循环或卡死，整个进程无法退出。

• 更安全的做法是：提前在 HTML 中用 window.setTimeout(() => { window.pdfReady = true; }, 200) 打点，再用 --run-script 配合 --javascript-delay 500
• --enable-local-file-access 必须开启，否则本地 file:// 加载 CSS/JS 会 403
• 别依赖 --footer-html 动态注入页码：它在每页单独渲染一次，若内含 JS，可能重复执行多次

字体嵌入和中文支持最容易漏掉配置

PDF 里中文变方块或英文乱码，90% 是字体没正确嵌入或 fallback 链断裂。Puppeteer 默认只带少量基础字体；wkhtmltopdf 则完全依赖系统字体。

• Puppeteer 启动时加 args: ['--font-render-hinting=none'] 可缓解部分模糊问题
• CSS 中强制指定： body { font-family: 'Noto Sans CJK SC', 'PingFang SC', sans-serif; }，并确保 Noto 字体已安装在宿主机
• 用 pdf.fonts 配置项（如 pdfmake）或 @font-face src: url(...) 时，路径必须是绝对路径或 base64 内联，相对路径在 PDF 上下文中无效

最麻烦的不是转不出 PDF，而是转出来的 PDF 在 Adobe Reader 里能正常显示，但在微信内置浏览器预览时字体崩塌、表格错位——这种兼容性落差，往往要到上线后才暴露。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《HTML转PDF会拖慢转换速度吗？【经验分享】》文章吧，也可关注golang学习网公众号了解相关技术文章。