使用Puppeteer转换HTML为PDF体积过大问题排查

你的问题核心是Puppeteer生成的PDF远大于Safari导出的，主要因为两者的渲染策略、图片压缩机制存在差异，以下是针对性的优化点：

1. 切换到新版Headless模式 #

旧版Headless（headless: true）的渲染引擎和普通浏览器差异较大，图片处理逻辑未做优化。换成新版Headless模式，更接近Chrome正常浏览器的渲染行为：

const browser = await puppeteer.launch({ 
  headless: "new", // 启用新版Headless模式
  args: [
    '--font-render-hinting=none',
    '--jpeg-quality=80', // 控制JPEG图片压缩质量
    '--png-quality=80', // 控制PNG图片压缩质量
    '--disable-gpu' // 禁用GPU渲染，避免异常
  ] 
});

2. 确保资源完全加载 #

setContent默认不会等待所有网络资源加载完成，可能导致Puppeteer重复渲染未加载的资源，或是使用未优化的图片源。添加waitUntil: 'networkidle0'确保所有资源加载完毕：

await page.setContent(htmlString, { 
  timeout: 0,
  waitUntil: 'networkidle0' // 等待网络空闲，确认所有资源加载完成
});

3. 优化PDF生成参数 #

调整PDF选项，匹配Safari的导出逻辑，同时避免视口与纸张格式冲突：

const pdfOptions: puppeteer.PDFOptions = {
  format: 'a3',
  printBackground: true, // 包含页面背景，和Safari导出行为一致
  preferCSSPageSize: true, // 优先使用CSS定义的页面尺寸，避免冗余缩放
  scale: 1 // 固定缩放比例，防止自动放大导致图片体积膨胀
};

4. 移除冲突的视口设置 #

你设置的defaultViewport: { width: 1366, height: 768 }会和format: 'a3'产生冲突，导致页面被强制缩放，增加PDF体积。直接移除该配置，让Puppeteer根据纸张格式自动适配视口。

修改后的完整代码 #

const generatePDFromHTML = async (htmlString: string, outputPath?: string) => {
    const browser = await puppeteer.launch({ 
        headless: "new",
        args: [
            '--font-render-hinting=none',
            '--jpeg-quality=80',
            '--png-quality=80',
            '--disable-gpu'
        ] 
    });
    const page = await browser.newPage();
    await page.setContent(htmlString, { 
        timeout: 0,
        waitUntil: 'networkidle0'
    });
    
    const pdfOptions: puppeteer.PDFOptions = {
        format: 'a3',
        printBackground: true,
        preferCSSPageSize: true,
        scale: 1
    };
  
    if (outputPath) {
        pdfOptions.path = outputPath;
    }
    
    const pdfBuffer = await page.pdf(pdfOptions);
    await browser.close();
  
    return pdfBuffer;
};

额外排查点 #

• 检查HTML中的图片是否为未压缩的原始格式，Puppeteer会直接嵌入原始图片，而Safari会自动压缩；
• 确认页面中是否存在隐藏的大元素（如超出视口的内容），Puppeteer会渲染所有元素，包括隐藏的，而Safari可能会自动裁剪。

内容的提问来源于stack exchange，提问作者Tey Kai Cong