3 分钟学会使用 Puppeteer 将 HTML 转 PDF

需求背景

1、网页存档与文档管理

需要将网页内容长期保存或归档为PDF，确保内容不被篡改或丢失，适用于法律文档、合同、技术文档等场景。PDF格式便于存储和检索。

2、电子报告生成

动态生成的HTML内容（如数据分析报告、仪表盘）需导出为PDF供下载或打印。PDF保留排版和样式，确保跨平台一致性。

3、电子邮件与营销材料

将HTML格式的新闻稿、促销内容转换为PDF附件发送，避免收件人因邮件客户端差异导致样式错乱。

4、学术与出版用途

论文、技术文档需从HTML转为PDF以满足出版要求。PDF支持高精度打印，且兼容学术平台的提交格式。

5、合同与表单签署

在线填写的HTML表单（如申请表格、订单）需转为PDF供客户签署或存档。PDF支持数字签名和加密。

方案一、wkhtmltopdf + python

https://wkhtmltopdf.org/

wkhtmltopdf 是一个开源命令行工具，通过 WebKit 渲染引擎将 HTML 内容转换为 PDF 文件。支持 CSS、JavaScript 和复杂的页面布局，常用于生成报告、发票、电子文档等场景。

不推荐，实测效果不佳，2020已停止维护。

到官网下载对应操作系统的安装包，这里是 Ubuntu24，安装指令如下：

sudo apt-get install xfonts-75dpi
sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb 

安装完成之后就可以使用命令转PDF了，例如把谷歌首页转PDF，也可以转本地html文件。

# 使用示例
wkhtmltopdf http://google.com google.pdf

方案二、Puppeteer

https://github.com/puppeteer/puppeteer

Puppeteer是一个由Google Chrome团队开发的Node.js库，提供高级API通过DevTools协议控制无头（Headless）或非无头的Chromium或Chrome浏览器。它常用于自动化测试、网页抓取、生成PDF或截图等场景。

推荐方案，效果最佳，高度还原浏览器打印效果

pnpm install puppeteer-core
# which google-chrome
/usr/bin/google-chrome

该方案需要安装谷歌浏览器，可以通过 which 指令查看已安装的 google-chrome 路径，使用示例如下：

// main.js
const puppeteer = require('puppeteer-core');
const fs = require('fs');
const path = require('path');
// 自动检测 Chrome 安装路径（支持 Linux/Windows）
const CHROME_PATHS = [
    '/usr/bin/google-chrome',      // Debian/Ubuntu 默认路径
    '/opt/google/chrome/chrome',   // 二进制实际位置
    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
];
(async () => {
   
    try {
   
        // 自动查找可用浏览器路径
        const executablePath = CHROME_PATHS.find(p => fs.existsSync(p));
        if (!executablePath) throw new Error('未找到 Chrome 浏览器');
        const browser = await puppeteer.launch({
   
            headless: 'new',          // 启用新一代无头模式
            executablePath,
            args: [
                '--no-sandbox',
                '--disable-setuid-sandbox',
                '--disable-dev-shm-usage',
                '--font-render-hinting=medium' // 提升中文字体渲染质量
            ]
        });
        const page = await browser.newPage();