如何把index.html转换成PDF格式？
用 Puppeteer 生成 PDF 最可靠
想把浏览器里渲染好的HTML页面，原汁原味地变成PDF文件？目前来看，Puppeteer是那个最稳妥的选项。它背后是完整的Chromium内核，这意味着你的CSS布局、特殊字体、SVG图标，甚至是Ja vaScript生成的动态内容，都能被真实地“打印”出来。相比之下，一些纯服务端的工具（比如weasyprint或者wkhtmltopdf）就常常让人头疼——样式丢失、布局错乱，各种报错防不胜防。
是不是经常遇到这些情况：调用Puppeteer.launch()时，直接报错Failed to launch chrome；好不容易生成了PDF，里面的字体要么缺失要么成了乱码；或者页眉页脚的位置总是不对劲。
别急，问题通常出在几个关键配置上：
- 确保Chromium存在：要么系统里已经安装了Chromium，要么就让
Puppeteer自己动手下载。初始化时，不指定executablePath（或者设为null），它就会自动处理。 - 正确加载本地文件：加载本地的
index.html，必须使用file://协议，并且路径一定要是绝对路径。可以这样写：await page.goto('file://' + require('path').resolve('./index.html'))。 - 搞定中文字体：如果内容里有中文，最保险的做法是在HTML里通过
@font-face显式声明并引用本地的TTF字体文件。或者在启动Puppeteer时，加上{ args: ['--font-render-hinting=none'] }这个参数。 - 明确页面尺寸：A4纸的尺寸和页边距，需要你明确告诉它：
page.pdf({ format: 'A4', margin: { top: '20px', right: '15px', bottom: '20px', left: '15px' } })。
避免 wkhtmltopdf 的兼容性陷阱
当然，很多人一开始会尝试wkhtmltopdf，因为它看起来命令行简单直接。但这里有个深坑：它的底层渲染引擎是QtWebkit，这个引擎对现代CSS（比如Flexbox、Grid布局）、ES6及以上版本的Ja vaScript，以及打印样式@media print的支持相当有限。所以，很多开发者遇到的“生成PDF是空白的”或者“所有样式都崩了”的问题，根源往往不是配置错了，而是引擎本身就不支持这些特性。
典型的报错信息长这样：QPainter::begin: Paint device returned engine == 0, type: 2；或者生成的PDF里只有光秃秃的文字，背景、边框全都不见了。
如果你确实需要使用它，有几个点必须注意：
- 别用系统自带的版本：不要通过
apt install wkhtmltopdf这类命令安装，像Ubuntu或Debian系统自带的版本通常太老旧。应该去官网下载静态编译的二进制版本。 - 开启本地文件访问：必须加上
--enable-local-file-access参数，否则它无法读取本地的CSS、JS或图片文件，导致资源全部404。 - 处理JS的局限性：通过
--no-stop-slow-scripts和--ja vascript-delay 2000参数，可以缓解因Ja vaScript执行不完全导致的内容缺失，但这只是权宜之计。对于交互复杂的页面，建议还是直接换用Puppeteer。
Node.js 脚本示例：三步跑通
理论说了不少，来看一个能立刻上手的例子。下面这个Node.js脚本是最小可运行版本，保存为html2pdf.js，然后直接运行node html2pdf.js即可：
const puppeteer = require('puppeteer');
const fs = require('fs').promises;
(async () => {
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
// 注意：路径必须绝对，且带 file:// 前缀
await page.goto('file://' + (await fs.realpath('./index.html')), {
waitUntil: 'networkidle0' // 等资源加载完再截图
});
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true // 否则 background-color/background-image 不生效
});
await browser.close();
})();
这里有两个关键细节值得划重点：waitUntil: 'networkidle0'这个选项比常用的'domcontentloaded'更保险，它能确保页面所有网络资源都加载完毕后再进行转换。另一个是printBackground: true，这个选项默认是false，但如果你希望PDF保留页面的背景颜色或背景图片，就一定要把它打开，这一点很容易被忽略。
字体与路径问题最容易被跳过
PDF生成过程中，90%的“玄学”问题都出在字体和路径上。明明在浏览器里预览得好好的，一到PDF里，中文字体就发虚，英文字体莫名其妙变成了宋体，图标也成了方块。这通常不是HTML写错了，而是在生成PDF时，没有正确地告诉Chromium引擎去哪里找到这些字体文件。
- 本地开发环境的陷阱：你在Chrome浏览器里能看到正确字体，并不代表Puppeteer也行。Puppeteer每次启动的都是一个全新的、干净的Chromium实例，它不会继承你系统里的字体缓存。
- 解决方案只有两个方向：其一，在CSS中使用
@font-face，并通过绝对路径引入TTF字体文件（例如url('/fonts/NotoSansCJK.ttc')），同时确保这个字体文件能和index.html一起，通过file://协议被加载到。其二，在启动Puppeteer时，通过启动参数直接指定系统字体目录，例如在Linux上可以这样设置：{ args: ['--font-render-hinting=none', '--font-cache-dir=/usr/share/fonts/'] }。 - 相对路径的坑：在
file://协议下，相对路径（href、src、@font-face里的url()）非常容易失效。最稳妥的做法是，在预处理阶段就把所有资源路径都转换成完整的file:///full/path/to/xxx格式。
说到底，真正卡住人的往往不是“哪个API怎么用”，而是路径协议、字体上下文和渲染时机这三个环节交织在一起产生的问题。遇到样式不对时，多打一行console.log(page.url())，看看页面实际加载的地址到底是什么，这比反复折腾CSS要有效得多。
