上周我把团队用了快三年的导出服务整套拆掉重写起因是一张带合计行的订单明细表被 PDF 截成了两页客户直接把截图甩到售后群里。做网页开发的人应该都有同感把一个 HTML 页面转换成 PDF听起来就是浏览器右键打印就能办到的事真正落地时全是细节。今天就把这套新的 HTML 转 PDF 技术方案完整梳理一遍从选型、实现到踩坑都写清楚争取让你看完能直接用。这套方案适用于报表导出、电子合同、工单打印、发票凭证这一类的“复杂 HTML 页面转 PDF”场景。它能解决传统方案中文字不可选、样式错乱、中文字体缺字、分页截断的问题。如果你是一名后端工程师、前端开发者或者负责内部系统自动化导出这篇文章应该能帮你省掉不少试错成本。1. 为什么“HTML 转 PDF”到今天还是个大坑1.1 一次导出事故把我逼上这条路先说事故本身。客户在系统里生成了一张销售订单明细表表格大概有六十行订单号、商品名、数量、单价、合计都在里面。结果导出成 PDF 后有一条订单的行被硬生生砍成两半上半页显示商品名和数量下半页显示单价和合计。客户一开始以为数据丢了售后客服查了半天发现数据没丢是 PDF 排版出了问题。这事看着不大但影响很恶劣。客户不关心你是用什么渲染引擎实现的他只看到“导出文件有 bug”。当天晚上我排查了现有导出链路发现服务用的是早年搭的“网页截图合成 PDF”方案先启动一个无头浏览器把 HTML 页面渲染成一张超长截图然后再按 A4 高度切分成多页拼成 PDF。这个方案的问题特别明显切分位置和 CSS 分页规则完全脱节表格中间被切开是必然的只是概率问题。更头疼的是这种方案生成的 PDF 本质上是图片集文字完全不能被选中、复制文件体积还大得离谱。一张订单页渲染完要两三 MB几十页就是几十 MB客户想转发到微信或者邮件都费劲。客服同事跟我抱怨过很多次说有些客户拿到 PDF 后想搜订单号结果 PDF 阅读器根本搜不出来。这就是图片型 PDF 的天生缺陷。1.2 传统方案的“三宗罪”截图、重排、字体在决定重写之前我把团队用过的几种 HTML 转 PDF 方案归了一下类问题基本可以浓缩成三个。第一宗罪是截图拼接。这种方案的实现路径很直白把页面渲染成一整张图再切图分页。它看起来“所见即所得”但牺牲了所有文本信息。搜索引擎无法解析PDF 解析工具读不到正文客户也无法对内容做二次编辑。但凡下游有“pdf 解析”“pdf 转 word”的需求这种方案直接判死刑。第二宗罪是页面重排失真。早期选择 wkhtmltopdf 的团队比较多但它的内核是基于老版 WebKit对现代 CSS Grid、Flexbox 布局支持得并不好。你写的是弹性布局到它那里可能变成块状堆叠你用了 box-shadow、圆角、渐变它要么不支持要么渲染出来和 Chrome 里完全是两个样子。后来有人转向 WeasyPrint但 WeasyPrint 对 CSS 的解析也有自己的脾性复杂的media print规则和页面计数器很不容易调通。每次小改动都可能引发大面积的样式回归维护成本不低。第三宗罪是字体缺字。如果服务器上没装中文字体或者只装了fcitx之类非嵌入字体生成的 PDF 会出现“豆腐块”。这个问题在 Docker 容器里尤其常见基础镜像往往只带一点点字体你 CI/CD 打包时稍微漏掉一步线上导出的 PDF 就会出现乱码。字体问题不解决前面渲染得再好看都是白搭。1.3 热搜词背后暴露的真实需求清单我在梳理方案时顺手看了下大家最近在搜什么发现“pdf解析”“网页pdf提取下载”“web页面pdf打印”“pdf转word”“pdf编辑器”“pdf转曲”这些词热度一直不降。这说明用户真正关心的不是“能不能生成一个 PDF”而是“生成的 PDF 能不能被继续使用”。如果 PDF 里的文字是不可复制的图片那么“pdf 解析”无从谈起“网页 pdf 提取下载”自然也没法做。反过来看如果生成的 PDF 本身带正确的文本层、书签目录和可控制的页面尺寸下游不管接“pdf 转 word”还是“pdf 编辑器”都会顺畅很多。所以我把这次重写目标定成了HTML 转 PDF 不只是“转格式”而是“排版输出”。我们要得到的是一个文、图、样式俱佳且带有文本层和元数据信息的真正可用的 PDF 文档。2. 整套方案的设计思路不跟浏览器内核对抗2.1 选型原则与常见备选方案的取舍确定了“排版输出”这个目标之后选型逻辑就清晰了渲染部分必须交给现代浏览器内核文件处理部分交给专业 PDF 工具中间连接层用自动化调试协议来控制。我对比了几个常见选项整理成一张表方案渲染能力文本层可控性适用场景wkhtmltopdf老版 WebKitCSS 支持弱有低简单页面早已不建议新项目用WeasyPrintHTML/CSS 解析器有中对 CSS 子集掌握熟练的团队PyQt5.QtWebEngineChromium 内核有中桌面端本地生成适合离线工具Puppeteer / PlaywrightChromium现代 CSS 全支持有高服务端批量导出最稳妥的选择自管 Chromium CDPChromium现代 CSS 全支持有最高需要深度控制打印任务的服务端场景PyQt5 的 QtWebEngine 本质也是 Chromium之前在桌面工具里用过一阵效果并不差但真正跑到服务端时并发调度、内存回收、容器化打包都要自己折腾。Puppeteer 和 Playwright 把 Chromium 的启动、连接和页面控制封装好平时用很方便可一旦遇到定制化的打印需求你还是得回到 DevTools Protocol 层去调参数。我们这次直接使用 CDP 通道就是为了避开中间层的“黑盒”把每个打印任务的状态握在自己手里。2.2 Headless Chromium CDP 后处理的组合架构整套方案分成三个模块渲染模块、控制模块、后处理模块。渲染模块就是一个常驻的chromium --headless实例。它不需要用 root 权限跑也不需要图形界面。启动时开启--remote-debugging-port9222Chromium 会暴露一个调试端口我通过/json接口拿到页面调试地址。控制模块用 Node.js 常驻进程管理任务队列。每个导出任务进来后控制模块先在 Chromium 中打开一个隐藏页面设置视口大小和打印样式等页面里所有资源加载完成并发出“可以打印了”的信号再向 CDP 发送Page.printToPDF命令。这个命令返回的是一段 Base64 编码的 PDF 字节流。后处理模块拿到字节流后再交给qpdf、pdf-lib这类专门工具做压缩、书签、加密、合并等操作。为什么要拆出后处理模块因为 Chromium 生成的 PDF 虽然排版准确但文件体积通常偏大书签结构可能不符合业务需求加密和权限控制也要额外处理。用专业工具做这些杂活比让 Chromium 硬扛要干净得多。2.3 和直接调用 printToPDF 的差别在哪有人可能会问这不就是 Puppeteer 的page.pdf()吗区别在于Puppeteer 确实封装了打印命令但它封不住业务层面的三个关键点打印样式规范、页面就绪信号、后处理链路。打印样式规范是指我们要求每个页面模板必须写清楚page尺寸和media print规则。如果只是随手写一个 HTML 就扔给page.pdf()CSS 没限制的话打印出来的页边距、页眉页脚会很随机。页面就绪信号是指我们不允许打开 URL 后立刻打印而是等待页面里的图表、图片、自定义字体全部加载完成再触发打印。这套逻辑是我自己实现的页面内window.__printReady机制。后处理链路就更重要了。page.pdf()生成完的 PDF 是一个“毛坯”需要压缩、加书签、加密。把这层逻辑写到控制模块里才能保证不管上游模板怎么变最终交付的文件都满足同一个标准。3. 从 HTML 模板到 PDF 后处理的落地过程3.1 写一份能“打印”的 HTMLpage 与 media print很多前端对打印样式不熟悉但 HTML 转 PDF 能不能稳定输出其实一半的功夫在 CSS 上。我的经验是模板里必须显式声明page规则否则 Chromium 会按默认的 Letter 纸型输出A4 用户在打印时就会遇到尺寸错位。一个比较稳妥的打印样式模板是这样的page { size: A4; margin: 18mm 14mm 16mm 14mm; } media print { body { font-family: Noto Sans CJK SC, Microsoft YaHei, sans-serif; color: #1f2328; font-size: 12pt; line-height: 1.6; } .no-print { display: none !important; } a[href]::after { content: ( attr(href) ); } table { width: 100%; border-collapse: collapse; } thead { display: table-header-group; } tr { break-inside: avoid; } }这里有几个容易被忽略的点。size: A4是声明最终纸型配合 CDP 的preferCSSPageSize: trueChromium 会优先采用 CSS 里定义的尺寸而不是命令参数里的默认值。thead { display: table-header-group; }可以让表格在跨页时每页自动重复表头客户不会出现“翻到第二页不知道列名是什么”的情况。tr { break-inside: avoid; }则是避免单行表格被截断这正是我那次事故的直接解药。如果你需要更复杂的效果比如首页不显示页码可以用page:first需要左右页不同的页边距可以用page:left和page:right。很多阅览器打印的细节CSS Paged Media 标准都已经覆盖到了。3.2 通过 CDP 调用 Chromium 的 Page.printToPDF页面模板准备好之后控制模块的工作就是连接 Chromium打开 URL再调用打印接口。我这里有段用 Node.js 写的最小示例const CDP require(chrome-remote-interface); const fs require(fs); (async () { const client await CDP({ port: 9222 }); const { Page, Runtime } client; await Page.enable(); await Runtime.enable(); await Page.navigate({ url: file:///tmp/report.html }); // 等待页面内部的自定义就绪信号 await Runtime.evaluate({ expression: new Promise((resolve) { const check () { if (window.__printReady) { resolve(); } else { setTimeout(check, 50); } }; check(); }) , awaitPromise: true, timeout: 15000, }); const { data } await Page.printToPDF({ printBackground: true, displayHeaderFooter: true, headerTemplate: span stylefont-size:9px; margin-left:0.4in;/span, footerTemplate: div stylefont-size:9px; width:100%; text-align:center; color:#999;第 span classpageNumber/span 页 / 共 span classtotalPages/span 页/div, preferCSSPageSize: true, }); fs.writeFileSync(output.pdf, Buffer.from(data, base64)); await client.close(); })();这里面最容易被忽略的就是“等待就绪”。很多情况下页面里的图表是异步渲染的图片也是懒加载的如果你等load事件结束就打印很可能输出一张带空白的 PDF。我在页面模板里埋了一个window.__printReady信号等所有异步任务执行完毕后再置为true。控制模块定时轮询这个信号超过 15 秒就按超时处理你能清楚地看到任务卡在哪一步。3.3 后处理三件套压缩、书签与加密Chromium 打印出来的 PDF 虽然准确但体积控制一般。尤其当你嵌入中文字体子集时文件可能比想象中大。我们会用qpdf做一次压缩qpdf --object-streamsgenerate --compress-streamsy input.pdf output.pdfqpdf能把 PDF 里的对象流重新组织压缩页内容流文件名从 input 到 output同一个文件不要直接覆盖否则容易出问题。实测压缩率经常能到 30% 到 50%20 页的彩色报表从十几 MB 压到 4 MB 左右。书签目录这块我在项目里用的是pdf-lib。Chromium 自动生成的书签结构往往比较简单电子合同的目录一般需要“合同标题”“附件一”“附件二”这样的结构化导航。用pdf-lib可以读入 PDF手动添加 outline 节点再把文档保存输出。如果需要给 PDF 加打开密码或限制复制打印qpdf的加密命令也很方便qpdf --encrypt user_password owner_password 256 -- generate output_encrypted.pdf注意加了 256 位加密后某些老版本 PDF 阅读器可能打不开如果客户群体不确定我会建议先不透传加密让业务层决定是否要二次加密。3.4 服务化封装输入 HTML输出 PDF 的接口设计方案不能只停留在命令行我把它封装成了内部的服务接口。接口定义很简单传入一个 HTML 字符串或者一个页面 URL返回 PDF 文件流。POST /api/html-to-pdf Content-Type: application/json { url: https://example.com/report?..., pageSize: A4, filename: 订单报表_20250101.pdf }服务内部维护一个任务队列把同一时间到达的大量导出请求排队处理。为什么不直接用child_process每个任务起一个 Chromium因为 Chromium 启动就要几百毫秒频繁启停既慢又浪费内存。常驻一个 Chromium 实例更经济但并发打印任务必须串行或限量否则多个Page.printToPDF同时跑会互相干扰。我们的控制模块里队列最大并发数设为 2任务通过 Redis 做持久化即使服务重启也能恢复未完成的任务。此外接口需要一个超时机制。我们把单个任务的最大等待时间设为 60 秒超过就返回失败状态并输出当时的页面控制台日志。页面加载失败的定位效率一下子提高了不少。4. 跑通之后才暴露的 5 个真实问题4.1 表格分页把行拦腰截断第一版上线后最容易被用户感知的坑就是长表格分页。即便你在 CSS 里写了tr { break-inside: avoid; }在复杂表格的嵌套下仍然可能出现“一行被截断”的情况。后来我发现原因在于行内的td里包含了一个设置了min-height的divChromium 在计算分页时把内层div当成了独立的盒子仍然允许它在行中间断掉。解决方法是把避免分页的属性应用到更细的层级上td, th { break-inside: avoid; }对纯文本单元格来说光写在tr上还不够必须让每个单元格本身也不可分页。另外表格外层如果有overflow: hidden也会干扰分页判断打印样式里最好改成overflow: visible。4.2 Linux 服务器中文字体缺字把服务部署到 Docker 后中文字体的问题“准时”找上门。开发机上渲染正常一进容器导出的 PDF 里中文全部变成方框。排查下来发现基础镜像里只装了dejavusans没有中文字体。我当时的解决路径是先安装字体包apt-get install -y fonts-noto-cjk然后清除字体缓存fc-cache -f这里还有一个隐蔽的坑即使安装了整体字体Chromium 计算页面字体时可能因为font-face声明不对导致某些特殊字符比如序号“①”、生僻字缺失。我的经验是同时把 Noto Sans CJK 的字重配好并且在模板里显式声明font-family: Noto Sans CJK SC不要依赖字体 fallback。4.3 图表、图片还没加载完就打印打印空白图表的问题在动态数据较多的报表里特别常见。ECharts 渲染需要执行 JavaScript图片如果是懒加载模式更要等待滚动位置触发。最开始的方案是等window.load但图表库经常会从 CDN 拉数据load事件结束后异步任务还在跑。我们后来在页面里统一注入了“打印就绪”的逻辑不只监听load还等待以下条件页面里所有img图片元素的complete属性为truedocument.fonts.status是loaded如果有 ECharts 实例调用echarts.getInstanceByDom(dom).getDataURL()能拿到非空内容。这些条件满足后再window.__printReady true。如果个别任务迟迟不就绪就通过页面控制台日志定位是哪个资源卡顿。这个方法帮我们排掉了很多偶发性的空白页问题。4.4 页眉页脚和页码的“隐形规则”CDP 的displayHeaderFooter参数看起来很友好但它的headerTemplate和footerTemplate用的是受限制的 HTML很多常规 CSS 属性都不生效。字体大小只能通过内联font-size控制且默认单位和打印环境绑定并不是你写12px就一定 12 像素。我的经验是页眉页脚模板里尽量只使用简单的inline-block和内联样式不要依赖外部样式表。页码部分通过span classpageNumber/span和span classtotalPages/span占位字体颜色用十六进制不用 rgba因为某些 PDF 阅读器对透明色渲染会变成黑色块。还有一点如果 HTML 页面本身带了页脚信息比如“本页为第 X 页”打印时一定要在media print里隐藏否则会出现一套页面自带页脚、一套 CDP 注入页脚双重输出非常难看。4.5 二维码和 SVG 发糊订单票据上经常有二维码如果二维码是网上下载的 PNG 图片尺寸不够大的话打印出来会有明显的锯齿。二维码在屏幕上能扫但在高清打印下就很勉强。这块的解法是把二维码生成方式从“图片”改成“矢量”。我在模板里用了qrcode库生成 SVG 字符串然后内联进 HTML。SVG 在打印时按矢量方式渲染可以无限放大不模糊。记得给 SVG 设置明确的width和height否则 CDP 会根据默认尺寸输出一个奇怪的大小。除此之外Charts 生成的图表一定要在打印样式里保证容器宽度是固定的不要用百分比。如果百分比宽度在页面加载时还没完全计算好打印就会按初始宽度输出图表比例会错位。5. 实测表现、适用范围与后续扩展5.1 20 页报告的实测数据我在内部跑了一个压测案例一份 20 页的销售汇总报告包含 8 张图表、6 个明细表格、封面和目录。用这套新方案的生成时间稳定在 3 到 5 秒最终 PDF 文件大小在 780 KB 到 1.2 MB 之间。对比旧的“截图拼接方案”20 页报告生成时间接近 9 秒文件大小动辄 20 MB 以上而且文字完全不可搜索。新方案的文字可以直接复制目录书签可以在阅读器里点击跳转文件体积也适合微信邮件传输。最直观的收益是客服那边终于不用再手动给文件“瘦身”了。文件体积能压下来的原因主要有两个一是 Chromium 生成的是原生 PDF 内容流而不是嵌入整张位图二是qpdf后处理对对象流做了压缩。你以为“打印”是简单的事情实际上字节流处理这些细节对最终体验影响极大。5.2 这套方案适合谁不适合谁总结一下这套组合方案最适合的场景是常见的在线报表、电子合同、工单打印、发票凭证、业务表格导出。尤其是 HTML 页面里的表格和图表比较多、对 CSS 还原度要求高的项目Chromium 内核的兼容性可以省掉很多布局踩坑。但它也不是万能的。如果你的核心需求是“一本几百页的书”这种专业排版需要精确控制页码规则、目录层级、跨页对齐那应该用 LaTeX 或者专业的排版软件而不是 HTML 打印。如果你是做纯桌面离线工具不希望环境里装一个常驻 Chromium 服务那 PyQt5 的 QtWebEngine 可能更合适。如果页面里的数据量极大比如一次性导出十万行以上的表格也应该考虑分批生成 PDF 再合并而不是让 Chromium 渲染整个页面。5.3 后续我准备继续做的方向这套方案稳定运行一段时间后我准备把打印模板里的通用 CSS 沉淀成一套内部组件库让不同业务线的报表可以复用同一套分页、页眉页脚和字体策略。另外因为生成的 PDF 带完整文本层下一步想接一个“pdf 解析”模块从 PDF 里抽取关键字段这样下游系统可以直接把导出文件再导入回来形成一个闭环。还有一个小插曲有同事问能不能直接给生成的 PDF 加公司 logo 水印。用qpdf在页面内容流上做 overlay 不太方便但如果只是加文字水印正好可以复用Page.printToPDF的模板逻辑在页面里的固定位置放置一个半透明层让它只在水印元素上显示。这个方案已经在试了等稳定之后我再来更新。最后说一点我自己的心得HTML 转 PDF 这件事最忌讳的是把“转格式”当成“截图”。你越是只想抄近路后续的返工成本就越高。反过来把打印当成一种专门的排版输出从 CSS 到浏览器内核到后处理逐层管好这套东西才能成为真正可信赖的基础服务。