HTML转PDF方案详解：从Puppeteer到html2pdf.zip的完整实践

简介：面向Java开发者的HTML转PDF功能实现资源，基于pd4ml库完成从网页内容到高质量PDF文档的转换，解决了中文字体支持弱、复杂布局处理慢等常见痛点，尤其适合构建报告、电子书、发票等文档生成场景。资源包总体积37.03MB，共15个文件，以Java源码、编译后的class、Eclipse工程配置（.classpath/.project）、TrueType字体以及pd4ml相关jar依赖为主，打开即可在Eclipse中导入并快速了解工程结构。资源已吸引214人浏览学习，适合需要集成HTML转PDF能力、或想对比pd4ml与iText差异的开发者。使用者可通过源码深入掌握pd4ml的转换流程、字体配置与错误处理机制，并基于自带的中文字体直接处理中文内容，减少编码与字体兼容性方面的踩坑成本。 写这个项目之前，我先说下背景。工作中经常遇到需要把网页内容导出成 PDF 的场景：电商订单详情、后台报表、技术文档、发票面单，甚至我自己写的简历都希望一键变成 PDF。手动按 Ctrl+P 也不是不行，但一旦涉及批量处理、定时生成、动态数据填充，就必须走程序化方案。html2pdf 就是在这个背景下出现的常见打包项目，而 html2pdf.zip 这种打包形式，通常是指作者把整个工具或脚本工程压缩成 zip 发布，用户下载后解压即用，省去各种环境折腾。

我之所以想把这个标题里的东西拆开讲，是因为“html2pdf.zip”看起来是个很窄的词，其实背后牵扯了一套完整的技术链路——HTML 渲染、PDF 生成、样式处理、中文编码、分页控制，甚至连 zip 压缩包这个载体也有不少门道。这篇博文就围绕这套链路，把我实际趟过的坑和可落地的方案整理出来，适合正在做文档导出、报表系统、自动化生成 PDF 的开发者参考，也适合刚入门的同学当一份体系化笔记。

1. 先理清需求：html转PDF到底要解决哪几件事

1.1 从“浏览器另存为PDF”到程序化生成的差距

很多第一次做 PDF 导出的朋友会有个错觉：既然浏览器自带打印功能，那后端把 HTML 字符串丢给某个库，就能跟浏览器里看到的一模一样。实际上完全不是一回事。

浏览器另存为 PDF 时，负责渲染的是完整的 Chromium 内核，它会把 CSS 布局、图片懒加载、JavaScript 动态内容全部处理完，再按 A4 或自定义纸张切页。而绝大多数后端库（比如最原始的 iText、Flying Saucer）拿到 HTML 后，用的是一套简化版的 CSS 解析规则，对 flex 布局、grid 布局、CSS 变量、阴影、渐变这些现代特性支持很有限。换句话说，你在浏览器里看到的漂亮页面，转到后端库渲染后基本会崩成线性排列的方块。

html2pdf 这种项目真正想解决的问题，并不是“把 HTML 变成 PDF”，而是要做到尽可能高的视觉保真度。实现这个目标通常有两条路：一条是前端 jsPDF + html2canvas 的截图方案，另一条是后端调用无头浏览器（Headless Chromium）的方案。两条路的取舍，我放到下一节细说。

1.2 HTML转PDF的两条技术路线对比

我在实际项目里把这两条路线都跑过一遍，各自的优缺点非常鲜明。对于中小型项目，前端直接生成的优势是部署简单，不需要单独起一个 PDF 服务，也不会占用服务器 CPU。它的核心原理是把页面上某个 DOM 节点用 html2canvas 逐像素截成图片，再塞进 jsPDF 的多页画布里。但它的短板也很致命——生成的是图片型 PDF，文字不可选中、不可搜索、文件体积大，而且对高分屏设备的分辨率适配很麻烦，比如用 2x 的设备像素比截图，图片尺寸翻倍，页数和内存占用跟着涨。

后端无头浏览器方案则是让程序去驱动一个真实浏览器（比如 Puppeteer 控制的 Chromium、playwright 控制的 WebKit/Chromium），调用浏览器自带的“打印到 PDF”能力。因为走的是浏览器的排版引擎，CSS 的还原度最高，生成的 PDF 也是带文本层的矢量文件，可以搜索、可以复制。缺点是环境依赖重，首次启动浏览器进程会有一两秒延迟，高并发场景下需要做进程池或专门的渲染服务。html2pdf 相关的项目里，绝大多数维护时间久、口碑不错的，都倾向于走 Chromium 这条路线，原因就是它先把“渲染准确性”这个最核心的指标稳住了。

2. 方案选型：为什么有的项目选wkhtmltopdf，有的选Puppeteer

2.1 三代工具链的进化逻辑

早期 HTML 转 PDF 的标杆是 wkhtmltopdf，它基于 Qt WebKit 排版内核，一条命令就能把网页转成 PDF。我之前在一个老项目中用过它，优点是部署简单（直接下载编译好的二进制丢服务器上）、资源占用低；缺点是内核停留在老版本 WebKit 上，很多新 CSS 属性不支持，比如display: grid从开始就不支持，CSS 变量更没影了，页面复杂了就得靠 hack 去兼容。

之后火起来的就是 Puppeteer / Playwright。Puppeteer 是 Google 官方团队维护的 Node 库，它把无头 Chrome 的操作封装成一套很友好的 API。核心用法就三步：打开 page、设置printMediaType、调用page.pdf()。因为它驱动的就是 Chrome DevTools Protocol，等于让 Chrome 完整渲染页面后再导出，所以对前端技术栈的兼容性是最好的。

选型的底层逻辑其实就一条：看你的页面要还原到什么程度。如果只是简单的表格、文本、固定布局，老一代轻量方案完全够；如果页面里有 Vue/React 组件、ECharts 图表、Element Plus 这类复杂的 CSS 体系，直接上 Puppeteer 或 Playwright，别再跟排版较劲。

2.2 为什么用zip发布而不是直接源码托管

谈到 html2pdf.zip 中这个.zip后缀，我多说一句。在 GitHub 上托管项目，用户终究要学会git clone或者去 Release 页面找压缩包，很多非程序员用户会在这一步劝退。把整套工程打成 zip 发布，本质上就是降低使用门槛：下载、解压、运行，三步走。尤其工具类项目，用户目标不是看代码，而是“赶紧把这个 PDF 跑出来”，zip 是最直观的载体。

另外，打 zip 包里还可以刻意排除掉node_modules、.git目录、日志文件这类体积大户，让压缩包保持在十几兆以内。用户拿到后只要按README里的说明执行npm install或直接运行已经打包好的可执行文件即可。有后人上传源码时忘记把依赖打全，解压后报各种模块找不到，这种经历估计不少人都有过。所以如果哪天你发布一个 html2pdf 工具，建议额外做一个“免安装版”，把依赖也塞进 zip，用户解压即用，口碑会好一个台阶。

3. 实操：用Puppeteer搭一个能用的html2pdf服务

3.1 最小可用工程的结构设计

我这边用一个 Node.js 工程来演示，目标很明确：接收一段 HTML 或 URL，输出一个 PDF 文件，并且处理好常见的页眉页脚和分页。工程结构大致是这样：

html2pdf/ ├── src/ │ ├── index.js # 入口，解析参数 │ ├── renderer.js # 封装 Puppeteer 的页面渲染逻辑 │ └── pdf.js # 生成 PDF 并写入文件 ├── assets/ │ └── template.html # 内置模板，方便测试 ├── output/ # 生成的 PDF 放这里 ├── package.json └── README.md

为什么要把渲染器和 PDF 写入拆成两个模块？一个很实际的考量是：渲染器这一层未来很可能要替换。我今天用 Puppeteer，明天可能觉得 Playwright 的浏览器矩阵更香，只要保证renderer.js对外的方法签名不变，业务代码就不需要动。

3.2 核心代码实现要点

先看renderer.js里最关键的加载页面逻辑：

const puppeteer = require('puppeteer'); async function renderPdf({ content, format = 'A4', margin = '20mm' }) { const browser = await puppeteer.launch({ headless: 'new', args: ['--no-sandbox', '--disable-setuid-sandbox'], }); try { const page = await browser.newPage(); // 如果是 HTML 字符串，用 setContent 加载；如果是 URL，可以改用 page.goto await page.setContent(content, { waitUntil: 'networkidle0' }); await page.emulateMediaType('print'); const pdf = await page.pdf({ format: format, printBackground: true, margin: { top: margin, bottom: margin, left: '15mm', right: '15mm' }, displayHeaderFooter: true, headerTemplate: '<span style="font-size:10px;padding-left:15mm;">内部资料</span>', footerTemplate: '<span style="font-size:10px;padding-right:15mm;">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</span>', }); return pdf; } finally { await browser.close(); } } module.exports = { renderPdf };

这段代码有几个细节值得重点说。headless: 'new'是新版无头模式，比旧的头模式更稳定，内存占用也小一些。networkidle0表示页面 500 毫秒内没有网络请求才继续往下执行，这是避免图片、脚本没加载完 PDF 就空白的关键。emulateMediaType('print')会让页面进入打印样式模式，这样你在 CSS 里用@media print写的规则才会生效。

displayHeaderFooter: true配合headerTemplate和footerTemplate可以给 PDF 批量加页码和标题。不过要注意，Puppeteer 默认会在页眉页脚里带一串日期和标题 URL，如果不想要，必须显式在模板里覆盖掉。我之前就遇到过用户反馈“页脚怎么有 Chrome 的版本号”，排查半天才发现是默认模板在作怪。

3.3 处理 CSS 分页、字体和自适应宽度

HTML 转 PDF 时最容易翻车的三个点就是分页、字体、宽度。

分页控制：先在全局 CSS 里加好打印规则：

@page { size: A4; margin: 20mm; } @media print { .no-print { display: none !important; } .page-break-before { break-before: page; } .page-break-after { break-after: page; } /* 避免表格行被截断到两页 */ tr, .avoid-break { break-inside: avoid; } }

break-inside: avoid这个属性很实用，它能让一段文字或一个表格行整体挪到下一页，而不是从中间被劈开。批量导出的长表格里，这是刚需中的刚需。

字体问题：如果在 Linux 服务器上跑，系统没有 Windows 的那些中文字体，PDF 里的中文就会变成“豆腐块”或乱码。解决方案是在服务器上安装字体，或者直接在本地打包字体目录，通过@font-face引入。建议先用下面的命令检查一下服务器字体：

fc-list :lang=zh

如果输出为空，说明一个中文字体都没有，务必先装（比如fonts-noto-cjk或微软雅黑对应的可商用字体）。不然代码写再好，PDF 渲染出来也是没法看的。

自适应宽度：有些页面上有固定宽度为 900px 的容器，转为 PDF 后内容会被裁掉一半。解决办法是在打印样式中固定好页面宽度：

@media print { body { width: 100%; } .container { max-width: 100% !important; } }

还有一个更好用的策略：在浏览器里先把视口宽度设置成 PDF 对应的像素宽度，比如渲染 A4 横向内容时物理像素为 1123px，那就用page.setViewport({ width: 1123, height: 794 })加载页面。这样页面里的大部分响应式布局都会按这个宽度来算，出问题的概率大大降低。

4. 实操过程与核心环节实现：把工具跑起来

4.1 从部署到生成第一个PDF的完整流程

部署步骤不复杂，但每一步都有讲究。先把项目从 zip 包里解压出来，然后安装依赖。

# 1. 初始化项目 npm init -y # 2. 安装 puppeteer npm install puppeteer # 3. 写入口文件（下面有个简化版可直接用） node src/index.js

如果是初次在服务器上跑 Puppeteer，大概率会遇到缺少系统依赖库的问题，比如：

error while loading shared libraries: libX11-xcb.so.1

这是因为 Chromium 需要一批图形界面相关的动态库。在 Ubuntu/Debian 系上通常执行：

sudo apt-get install -y \ gconf-service libasound2 libatk1.0-0 libc6 libcairo2 \ libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 \ libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 \ libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 \ libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 \ libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 \ libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation \ libappindicator1 libnss3 lsb-release xdg-utils wget

装完之后跑一下验证脚本：

// smoke-test.js const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('data:text/html,<h1>hello pdf</h1>'); await page.pdf({ path: 'smoke.pdf' }); await browser.close(); console.log('ok'); })();

能用浏览器把hello pdf成功输出成smoke.pdf，说明整个链路是通的，接下来再接入真正的业务模板。

4.2 批量生成PDF时的参数计算与性能优化

批量生成场景里，一个很容易被忽略的参数是并发实例数。Puppeteer 虽然能干，但每次 launch 都会起一个完整的浏览器进程，假设一条导出任务要处理 1000 个订单，如果不做控制，瞬间 1000 个 Chromium 进程能把服务器内存打爆。

比较稳的做法是全局只保留一个浏览器实例，多个页面共用，再控制页面级别的并发数。

const browser = await puppeteer.launch({ headless: 'new' }); async function processBatch(urls, concurrency = 5) { const results = []; const workerCount = Math.min(concurrency, urls.length); for (let i = 0; i < urls.length; i += workerCount) { const batch = urls.slice(i, i + workerCount); const batchResults = await Promise.all(batch.map(async (url) => { const page = await browser.newPage(); // 每个任务开新标签页 try { await page.goto(url, { waitUntil: 'networkidle0' }); return await page.pdf({ format: 'A4' }); } finally { await page.close(); // 用完立刻关页面，不关浏览器 } })); results.push(...batchResults); } return results; }

这里的核心是“共用浏览器进程，串行分片处理任务”，用concurrency = 5时最多同时跑 5 个页面。跑完后统一browser.close()，避免重复创建销毁浏览器造成的严重资源浪费。很多线上导出服务效率炸裂，往往就是没做好这一层控制。

如果是超大 PDF（几百页），还可以考虑用 HTML 模板内嵌数据的方式一次性渲染，而不是逐页拼装，这个优化空间更大。用一个循环在服务端把 1000 行订单拼成一个长 HTML，再一次性转成 PDF，速度往往比逐条生成快得多。

4.3 集成到HTTP服务里提供在线转换能力

很多场景不只是本地生成，还要对外提供接口。用一个简单的Express服务包一下：

const express = require('express'); const { renderPdf } = require('./renderer'); const app = express(); app.use(express.json()); app.post('/api/html2pdf', async (req, res) => { const { html, filename = 'output.pdf' } = req.body; try { const pdfBuffer = await renderPdf({ content: html }); res.setHeader('Content-Type', 'application/pdf'); res.setHeader('Content-Disposition', `attachment; filename=${filename}`); res.send(pdfBuffer); } catch (err) { console.error('html2pdf error:', err); res.status(500).json({ error: err.message }); } }); app.listen(3000, () => console.log('html2pdf service running on port 3000'));

记得在服务入口加一层Content-Security-Policy或者做 HTML 元素白名单过滤。因为用户传 HTML 上来，万一里面写了恶意脚本，虽然 Puppeteer 沙箱能兜底，但作为公共服务还是要防一手。至少要把<script>标签过滤掉，或者只允许加载来源可信的图片。

5. 常见问题与排查技巧实录

5.1 解压和运行阶段的典型报错

我根据这几年在群里看到的问题，整理了一份高频率问题速查表，适用场景就是从网上下载各种 html2pdf.zip 或自己打包分发时遇到的问题。

多说一句 zip 密码这件事：我们发布工具时一般不建议给压缩包设密码，因为很多小白用户遇到密码提示就卡住了。真要保护源码，放到私有仓库，而不是用薄弱的 zip 加密给别人添堵。

5.2 内容渲染类问题与定位思路

内容渲染类的问题比环境报错更难查，因为程序没有报异常，但输出 PDF 与预期不符。

问题一：PDF 里中文全部变成方框。先fc-list :lang=zh看字体，再用@font-face显式引入一个中文字体文件，最后才考虑是不是 CSS 字重被浏览器忽略。经验上 80% 是服务器没字体。

问题二：页面显示正常，PDF 里布局乱掉。八成是没加emulateMediaType('print')，页面根本没进入打印模式。另一个高频原因是 flex 布局在旧版 WebKit 内核里失效，如果用的 wkhtmltopdf 就得手动多写 table 布局兜底。

问题三：图片在 PDF 里不存在。多半是图片加载时机晚于 PDF 生成。把waitUntil从默认的load改成networkidle0，或者在生成之前显式等待图片的complete状态：

await page.evaluate(async () => { const imgs = Array.from(document.images); await Promise.all(imgs.map(img => img.decode())); });

5.3 输出文件体积与内存控制

最后说一下 PDF 体积膨胀问题。如果 HTML 里嵌入了大量 base64 的高清图片，生成的 PDF 动辄几十上百兆。这时候可以在生成前对图片做一次压缩，或者在page.pdf()前统一降低图片质量。比如把用户上传的截图先压到 1200px 宽再插入页面：

async function compressImages(page) { await page.evaluate(async () => { const imgs = Array.from(document.images); await Promise.all(imgs.map(img => new Promise(resolve => { if (img.complete) { const canvas = document.createElement('canvas'); const scale = Math.min(1, 1200 / img.naturalWidth); canvas.width = img.naturalWidth * scale; canvas.height = img.naturalHeight * scale; const ctx = canvas.getContext('2d'); ctx.drawImage(img, 0, 0, canvas.width, canvas.height); img.src = canvas.toDataURL('image/jpeg', 0.8); img.onload = resolve; } else { resolve(); } }))); }); }

在 html2pdf 场景中，这个前处理能直接砍掉一半以上的文件体积，同时肉眼几乎看不出清晰度差异。

6. 我的个人实践心得

这套 html2pdf 方案我前前后后维护了一年多，踩过的坑比上面写的还多。最想把一句话送给正在折腾的人：先用最简单的方式跑通全链路，再回头做优化，别一上手就追求完美架构。很多人一开始就在纠结用 Puppeteer 还是 Playwright，其实只要先跑出一个能用的 PDF，工具选型这件事的答案自己就会浮出水面。

最后再分享一个实用技巧：调试渲染问题时，给 Puppeteer 加上headless: false打开有头模式看一遍页面实际效果，往往一眼就能定位 CSS 问题所在，比反复猜测快得多。而且开发阶段可以把slowMo: 50加上，每个操作都放慢 50 毫秒，基本能看清楚页面加载的整个流程。等所有问题解决了，再切回无头模式跑生产任务。

html2pdf 这个方向看起来简单，实际跑一遍会发现它连接了浏览器内核、CSS 排版、打印协议、字体管理和性能调度多个位面。把这一条链路真正摸透，以后不管遇到什么“网页转图片”“网页转长图”的需求，你都会觉得轻车熟路。

本文还有配套的精品资源，点击获取