为何Puppeteer在Windows环境下PDF生成超时失效？

核心问题 #

1. 超时配置层级错误：你在page.pdf()中设置的timeout:0仅控制PDF生成方法的超时，但报错提示的是浏览器与Node.js进程间的通信协议超时，需要在puppeteer.launch()中配置protocolTimeout。
2. 新版无头模式兼容性：Puppeteer 22+版本中，headless: true等价于启用headless: "new"模式，该模式在Windows环境（尤其是虚拟机）中存在PDF生成卡顿的兼容性问题。
3. 沙箱机制干扰：Windows系统（虚拟机）下Chrome的沙箱权限限制，可能阻塞PDF渲染流程。

修复配置 #

在puppeteer.launch()中添加以下关键配置：

• protocolTimeout：设置协议通信超时时间（单位毫秒，0表示无超时）
• 切换至旧版无头模式headless: "old"，或配合禁用沙箱使用新版模式
• 添加--no-sandbox等参数禁用沙箱及GPU渲染，规避Windows环境限制

修改后的代码 #

const puppeteer = require('puppeteer');
const fs = require('fs');

const init = async () => {
    try {
        const browser = await puppeteer.launch({
            headless: "old", // 改用旧版无头模式，提升Windows兼容性
            protocolTimeout: 30000, // 设置协议超时为30秒，可根据需求调整为0
            args: [
                '--no-sandbox',
                '--disable-setuid-sandbox',
                '--disable-gpu' // 禁用GPU渲染，避免Windows环境下的渲染异常
            ]
        });
        const page = await browser.newPage();

        await page.setContent('<h1>Hello World</h1>');
        await page.emulateMediaType('screen');
        await page.pdf({
            path: 'hello-world.pdf',
            format: 'A4',
            printBackground: true,
            timeout: 0
        });

        console.log('PDF Generated');
        await browser.close();
        process.exit()

    } catch (error) {
        console.log(error)
    }
};

init()

补充说明 #

• 若headless: "old"生效，说明新版无头模式在你的Windows环境存在兼容性问题，可暂时使用旧版，待Puppeteer后续版本修复后再切换。
• protocolTimeout是解决本次超时报错的核心配置，必须在launch()中设置，而非page.pdf()方法内。
• --no-sandbox在Windows虚拟机中尤为重要，虚拟机通常没有足够权限运行沙箱模式的Chrome实例。

内容的提问来源于stack exchange，提问作者ChethiyaKD