企业官网建设流程全解析

做了这么多年前端和自动化工具，我几乎每隔一段时间就会碰到有人问“怎么把HTML转成PDF”。这个问题看起来简单，网上方案一搜一大把，但真到自己上手的时候，坑一个接一个：样式变了、中文乱码、分页诡异、动态内容没加载出来……我今天就把自己实际折腾过、也在生产环境跑过很久的方案整理出来，从思路、选型到完整实操一次说清楚。这篇内容不吹“银弹”，只讲怎么根据场景选对路子、避开那些没人提醒你的暗坑。

1. 别急着找工具，先想清楚你的HTML长什么样

1.1 为什么市面上没有“唯一正确答案”

很多人喜欢搜“最完美的方法”，但做过的都懂，HTML转PDF根本没有通吃所有场景的万能方案。原因在于，HTML本身是流式文档，内容会根据视口宽度自动换行、伸缩，而PDF是固定版式的页面文档，一页就是一页，内容不能随便流动。这两者之间存在天然矛盾。

所以，第一步不是下载工具，而是先搞清楚你的HTML属于哪一类：

• 简单文本型：就是标题、段落、表格，几乎没有复杂样式，也没图片。
• 中等复杂度页面：有CSS布局、弹性盒子、栅格系统、图片、小图标。
• 重度交互型：需要先加载接口数据、等图表渲染完、等图片懒加载完成，甚至需要用户点击后才出现的内容。
• 打印特化型：为打印专门设计了CSS，比如A4纸张媒体查询、分页控制符、页眉页脚。

不同类型的页面，对应的方案完全不同。你让一个打印特化型的页面用虚拟打印机去出，效果大概率会很好；但让一个重度交互型页面用同样方式出，可能导出的是空白。这就是“最完美方法”这个词的陷阱：方案必须跟着场景走。

1.2 三条主流技术路线，各自擅长什么

• 浏览器内核渲染：典型代表是Puppeteer控制Headless Chrome、Playwright，以及老牌的wkhtmltopdf。这种方式用真实浏览器排版，CSS还原度最高。
• 虚拟打印驱动：比如Microsoft Print to PDF、Adobe PDF打印机。它走的是系统打印链路，适合把任何可打印内容“打印”成PDF，但可控性弱。
• 独立排版引擎：比如WeasyPrint、PrinceXML。它们直接解析HTML和CSS，不经过浏览器，对打印CSS支持得很好，但对现代CSS特性支持有限。

这三条路线对应不同的使用场景：浏览器内核适合复杂页面和自动化生产，虚拟打印适合临时救急和本地操作，独立排版引擎适合追求打印语义、重排版质量的批量任务。下面我就把最常用的浏览器内核方案掰开揉碎讲清楚。

2. 主力方案实操：用Headless Chrome做HTML转PDF

2.1 环境准备与第一个可运行例子

我目前的主力方案是Puppeteer，也就是用Node.js控制无头Chrome完成转换。之所以选它，是因为它背后是完整的Chromium内核，只要是Chrome能正常显示的页面，它基本都能还原成PDF，不需要额外处理CSS兼容性。

安装很简单，在一个空目录里执行：

npm install puppeteer

注意，这里有个小坑：puppeteer包默认会下载一个配套的Chromium浏览器，体积大概一百多兆。如果下载失败或者你不想重复下载，可以设置环境变量跳过，然后指向系统已有的Chrome：

npm install puppeteer --ignore-scripts

然后用系统Chrome时，启动参数里要加executablePath：

const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch({ executablePath: '/usr/bin/google-chrome', headless: 'new', args: ['--no-sandbox', '--disable-setuid-sandbox'] }); const page = await browser.newPage(); await page.goto('https://example.com', { waitUntil: 'networkidle0' }); await page.pdf({ path: 'output.pdf', format: 'A4', printBackground: true }); await browser.close(); })();

这段代码就是最核心的骨架。我个人建议第一次跑的时候先用一个本地HTML文件测试，不要直接上线上页面，方便排查问题：

await page.goto('file:///path/to/test.html', { waitUntil: 'networkidle0' });

本地文件只要注意文件路径写对，就不会有跨域和加载慢的困扰。如果这个最小例子能跑通，说明环境没问题，后面就是参数调优了。

2.2 page.pdf参数详解：从A4到自定义尺寸

page.pdf()的参数决定了PDF的物理形态。很多人只填一个path就完事，结果纸张大小、边距、背景全不对，还把锅甩给工具。我把自己常用的参数列一下，逐个说明含义：

需要注意，headerTemplate和footerTemplate里不能直接写普通样式，Chrome会忽略class内部的部分样式。正确的姿势是把样式写成内联style，字体大小单位最好用pt，因为页眉页脚模板运行在独立上下文里，默认字体非常小。

比如一个带页码的页脚模板：

<div style="width:100%; text-align:center; font-size:8pt; color:#999;"> <span class="pageNumber"></span> / <span class="totalPages"></span> </div>

pageNumber和totalPages是Chrome预留的类名，会自动填充当前页码和总页数，不需要自己写脚本。这一点特别实用，比你手动算页码靠谱得多。

2.3 页面内容“缺斤少两”：等待渲染完成的三种手段

做HTML转PDF时最头疼的问题之一，就是PDF里内容“少了”。常见场景包括：接口数据没加载完、图表插件还没画出来、懒加载图片没触发。解决这个问题，核心思路是“等”。

第一种等待方式是waitUntil配置，常用的有load、networkidle0、networkidle2。load只等页面load事件，如果页面有异步请求，大概率不够。networkidle0表示500毫秒内没有任何网络请求才算完，最严格；networkidle2允许最多两个连接，适合页面一直有长连接的情况。

await page.goto(url, { waitUntil: 'networkidle0' });

第二种方式是在页面内显式等待某个元素出现：

await page.waitForSelector('#chart-container canvas', { timeout: 30000 });

这个方法适合知道关键渲染节点的场景。比如页面里有个报表区域，一定要等canvas或svg渲染出来再截图，否则就是一张白纸。

第三种方式是自己控制延时，最直接但最不优雅：

await new Promise(r => setTimeout(r, 2000));

这个方法适合页面加载不稳定、但又不想写复杂等待逻辑的场景。我的习惯是：先用networkidle0，再补一个2到3秒的缓冲延时，双保险，实测下来稳定性提升非常明显。

3. 备选方案横向对比：什么时候换赛道

3.1 浏览器原生打印和虚拟打印机：适合“人肉操作”

如果你的场景是偶尔转换一两份文档，不想装一堆依赖，直接用浏览器打开HTML页面，按Ctrl+P，目标打印机选择“Microsoft Print to PDF”或系统自带的“另存为PDF”，一样能出结果。

但这种方式有两个致命短板：

一是不适合批量处理。你不可能手动打开几百个页面逐个打印，效率太低。

二是样式还原依赖打印预览设置。浏览器会默认去掉背景、调整页边距，用户得手动勾选“背景图形”选项，否则背景色直接消失。而且不同浏览器的默认设置还不一样，Chrome和Edge的打印选项位置不同，教别人操作的成本很高。

不过，对于“领导临时要看一版PDF”这种低频场景，虚拟打印机其实很靠谱。它不需要写任何代码，打开页面、Ctrl+P、选打印机，三步搞定。

3.2 wkhtmltopdf：老牌工具的能打与局限

wkhtmltopdf是一个老牌命令行工具，基于Qt WebKit内核。在Puppeteer流行之前，它几乎是自动化生成PDF的默认选择。我确实用过一段时间，它有几个优点：

• 上手极快，一条命令就能出PDF，不需要写任何代码。
• 提供--header-*和--footer-*参数，页码、页眉文字在命令行里直接配，运维友好。
• 长期维护，社区资料多，踩坑经验满天都是。

wkhtmltopdf --enable-local-file-access --footer-center "[page] / [topage]" --margin-top 15mm input.html output.pdf

但随着前端技术演进，它的局限也越来越明显。因为内核停留在WebKit的某个版本，很多新CSS特性不支持，比如flex和grid布局、CSS变量，解析出来往往和Chrome完全不一样。这在老项目里还能忍，新项目一旦用了现代CSS方案，基本就废了。

3.3 WeasyPrint和Playwright：按需选择

WeasyPrint是一个用Python写的独立渲染引擎，不走浏览器内核，直接解析HTML和CSS。它对打印CSS的支持非常讲究，尤其是分页控制、页边距、页眉页脚这些打印语义，做得很细。如果你生成的HTML本身就是面向打印设计的，没有复杂JavaScript，那么WeasyPrint的表现会让人惊喜，而且安装比Puppeteer轻量，适合部署在服务器上。

pip install weasyprint weasyprint input.html output.pdf

不过，WeasyPrint对JavaScript零支持，也没有完整的CSS Grid、Flexbox渲染能力。如果你的页面依赖前端框架，它并不适合。

Playwright则是Puppeteer的强力替代品。它的设计更现代，支持多浏览器内核，除了Chromium还能用Firefox和WebKit。如果你的页面在Chrome里渲染有差异，想用其他内核试一下，Playwright是更灵活的选择。代码写法和Puppeteer几乎同构，迁移成本非常低。

3.4 各方案对比一览

说句实话，我在实际工作中遇到最多的需求还是复杂Web页面自动生成PDF，所以Puppeteer方案用得最顺手。下面重点把我在这个方案里踩过、也最终解决的几个高频问题分享出来，这些都是文档里很少写清楚的地方。

4. 高频踩坑与排查锦囊

4.1 CSS样式丢失或错位，先从这两件事查起

转换后PDF样式和浏览器预览不一致，是最常见的抱怨。我排查这种问题有固定套路，先从两个方向查：

第一，检查printBackground参数。Chrome默认不打印背景色和背景图片，你以为样式丢了，其实是背景没被输出。把这个参数设为true，八成问题就解决了。

await page.pdf({ path: 'out.pdf', printBackground: true });

第二，检查页面里有没有媒体查询：

@media print { .nav { display: none; } }

只要浏览器判断当前处于打印模式，这些样式就会生效。如果这些CSS里写了隐藏关键内容的条件，那PDF里自然就会缺东西。

如果这两个方向都没问题，那就要看是不是CSS兼容性的锅。Puppeteer渲染的是Chromium，理论上兼容性是最好的，但如果你打印的是其他内核渲染的页面，偶尔也会翻车。此时可以切换Puppeteer对应的Chrome版本，或者改用Playwright调Firefox内核试试。

4.2 中文乱码与字体缺失的处理思路

中文乱码问题通常出现在两类环境中：一是Windows上部署的Web服务，二是精简版的Linux容器里没有安装中文字体。

Windows环境相对好处理，系统自带微软雅黑和宋体，只要HTML里指定了中文字体，Chrome渲染就没问题。Linux环境下系统默认不一定有中文字体，常见的情况是PDF里中文全部变成方块或者乱码。

解决办法是在服务器上安装字体，以Ubuntu为例：

apt install -y fonts-noto-cjk

安装之后，在HTML的CSS里明确指定字体族：

body { font-family: "Noto Sans CJK SC", "Microsoft YaHei", sans-serif; }

不要只写"sans-serif"，因为Chrome匹配字体时可能会选到一个不含中文字符的英文字体。

更稳妥的做法是直接通过CSS嵌入字体文件：

@font-face { font-family: "CustomFont"; src: url("/fonts/custom.woff2") format("woff2"); font-display: swap; }

把字体文件放在服务器上，通过相对路径或绝对路径引用，就能保证所有机器上输出一致。

4.3 分页控制不住：CSS打印技巧

分页是HTML转PDF里最需要耐心调的部分。默认分页规则由浏览器自动决定，但自动分页经常让表格的行被拦腰截断，或者标题孤零零落在页面底部。

控制分页主要靠三个CSS属性：

.avoid-break { break-inside: avoid; page-break-inside: avoid; } .page-break-before { break-before: page; page-break-before: always; } h2 { break-after: avoid; page-break-after: avoid; }

解释一下：

• break-inside: avoid：防止元素内部被分页，常用于表格行、卡片、代码块。
• break-before: page：强制元素从新一页开始，常用于每个大章节的标题。
• break-after: avoid：防止标题后紧跟分页，避免标题在页面底部，而正文跑到下一页。

另外，还需要配合浏览器的兼容写法。break-*是较新的标准，旧浏览器需要page-break-*前缀，两个一起写才能稳。实测下来，这个组合对表格和长文本的分页效果提升非常明显。

4.4 页眉页脚与页码模板怎么调才能用

页眉页脚模板是Puppeteer官方提供的能力，但很多人不会调。其实关键点就两个：

一是模板里的class样式必须写成内联样式，<style>标签的内容很可能被忽略。比如设置字体大小，直接在标签上写style="font-size:8pt"。

二是模板尺寸和边距由margin参数撑开。如果你没有设置margin的top和bottom，页眉页脚就显示不出来，因为Chrome只能把页眉页脚放在页面边缘的margin区域里。

await page.pdf({ path: 'out.pdf', displayHeaderFooter: true, headerTemplate: '<div style="font-size:7pt; margin-left:15mm;">内部文档</div>', footerTemplate: '<div style="width:100%; text-align:center; font-size:7pt;">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</div>', margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' } });

这个小技巧是我工作中用了很多次的。需要注意，模板里的边距与页面正文的margin是同一套体系，如果页眉内容比较长，需要适当加大top和bottom的边距，否则页眉会和正文挤在一起。

4.5 图表、懒加载图片与异步接口数据，最隐蔽的坑

很多报表类页面，图表是用Canvas或SVG绘制的，数据从接口异步加载，图片大量使用懒加载技术。这类页面转PDF时容易出“截图里数据是空白的”的状况，而且不是每次必现，时好时坏，最难排查。

我的建议顺序是：

1. 先强制等待接口完成。推荐用page.waitForResponse()来指定某个接口返回后再继续，比单纯等几秒更靠谱。
2. 再等待关键元素出现。
3. 最后加一个固定延时兜底。

await page.goto(url, { waitUntil: 'networkidle0' }); await page.waitForResponse(resp => resp.url().includes('/api/report') && resp.status() === 200); await page.waitForSelector('.chart-wrapper canvas'); await new Promise(r => setTimeout(r, 1500)); await page.pdf({ path: 'report.pdf', printBackground: true });

这个“接口等待 + 元素等待 + 延时兜底”的三段式写法，我一直在用，替换了不少无脑setTimeout，大幅减少了空数据概率。懒加载图片的话，可以在等待完后执行一次页面滚动到底部，触发图片加载：

await page.evaluate(async () => { await window.scrollTo(0, document.body.scrollHeight); });

然后再等几百毫秒出PDF，图片基本都能加载出来。

5. 工程化落地：把转换能力封装成稳定服务

5.1 服务端接口设计思路

用Puppeteer做转换，最好不要每次请求都重新启动一个浏览器实例。浏览器启动本身耗时几百毫秒到几秒不等，高并发场景下会直接把服务拖垮。

正确做法是把浏览器实例常驻内存，每个请求复用同一个实例，用browser.newPage()新开标签页处理，处理完关闭页面。这样省去了反复启动浏览器的开销，性能提升非常明显。

简单的服务端代码骨架如下：

const express = require('express'); const puppeteer = require('puppeteer'); const app = express(); let browser; app.use(express.json()); app.post('/html-to-pdf', async (req, res) => { let page = await browser.newPage(); try { await page.setContent(req.body.html, { waitUntil: 'networkidle0' }); if (req.body.waitFor) { await page.waitForSelector(req.body.waitFor); } const pdfBuffer = await page.pdf({ format: 'A4', printBackground: true }); res.type('application/pdf').send(pdfBuffer); } finally { await page.close(); } }); async function start() { browser = await puppeteer.launch({ headless: 'new' }); app.listen(3000); } start();

用page.setContent()可以直接传HTML字符串，不需要临时生成文件，适合接口化场景。这里要特别注意，如果HTML里引用了CSS或JS的相对路径，setContent需要配合baseURL参数，否则资源可能找不到。

5.2 批量生成与性能优化

批量生成大量PDF时，性能优化比单文件转换更讲究。我的经验是按并发窗口来控制，不要一次性开几十个page同时干活。Chrome每个页面都会占用一定内存，开太多容易导致崩溃。

推荐的批量策略是限制并发数，比如同时只跑4个任务：

const { default: PQueue } = await import('p-queue'); const queue = new PQueue({ concurrency: 4 }); const tasks = htmlList.map(html => queue.add(() => convert(html))); const results = await Promise.all(tasks);

sched用队列把任务串起来，既能保持资源占用稳定，又能让整体吞吐量不差。

另外，如果待转换的HTML非常多，而且彼此独立，可以先把HTML内容落成文件，再用Chrome的--print-to-pdf命令行参数去做无头打印，减少Node层面的内存开销。但这种方式灵活性弱，我一般只在绝对追求性能时才用。

5.3 安全隔离与资源清理

服务化之后，安全和稳定性问题就浮现出来了。首先要考虑的是页面内不可信的JavaScript。page.setContent()执行页面脚本时，如果HTML里包含恶意代码，它会在Chrome里运行，具备访问本地资源的可能性。所以，处理不可信内容时，最好给浏览器加--no-sandbox参数，并在独立容器里运行服务，避免直接暴露在主业务服务器上。

其次是资源清理。每次处理完一个页面，一定要关闭page，否则内存会随着请求数无限增长。Promise的finally，或者try...catch后的close()调用，都不能省。

最后是超时控制。网络请求不稳定、JS执行卡死，都会导致goto()或waitForSelector()挂起。建议给每个页面操作加超时时间：

await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });

超过30秒直接抛错，避免请求堆积导致整个服务不可用。

最后再分享一点我的真实体会

从最早用虚拟打印机手动打印，到后来折腾wkhtmltopdf，再到现在用Puppeteer和Playwright做出一套自动化转换服务，这个过程的体会是：方案不一定要最先进，但一定要匹配内容和流程。如果只是个人偶尔转几个页面，Chrome自带的“另存为PDF”完全够用，没必要为它搭一套Node服务。但如果你要批量生成报表、合同、工单，那Puppeteer这套自动化方案是绕不开的，值得花时间把框架搭好。

另外，无论你用哪个方案，拿到PDF后一定要看一遍再发出去。自动生成的PDF最大的风险就是“机器觉得没问题，人眼一看全乱了”。如果你要处理的页面特别复杂，建议在开发环境反复调整CSS打印样式和等待策略，我上面写的那些坑和套路，都是拿真实项目试出来的，照着走能少走很多弯路。