Puppeteer生成PDF时背景图片无法在所有页面显示的问题

问题描述 #

用Puppeteer将HTML转PDF时，背景图片仅在第一页显示；若把背景属性放到body的子div中（设置position: fixed、宽高100%），最后一页只有部分区域显示背景。需要让背景图片完整覆盖生成PDF的每一页。

解决方案 #

核心思路是用CSS固定定位容器承载背景，配合@page规则统一页面尺寸，同时调整HTML和body的基础样式避免布局冲突：

修改后的完整代码 #

let args = [
    '--no-sandbox',
    '--disable-setuid-sandbox',
];

let options = {
    format: 'A5',
    printBackground: true,
    preferCSSPageSize: true
};

const html = `
<html style="-webkit-print-color-adjust: exact; margin: 0; padding: 0;">
<head>
    <style>
        @page {
            size: A5;
            margin: 0;
        }
        .full-bg {
            position: fixed;
            top: 0;
            left: 0;
            width: 100vw;
            height: 100vh;
            background-image: url('https://...image.JPEG'), linear-gradient(rgba(0,0,0,0.5),rgba(0,0,0,0.5));
            background-size: cover;
            background-repeat: repeat;
            z-index: -1;
        }
        body {
            margin: 0;
            padding: 0;
            color: white;
            position: relative;
        }
    </style>
</head>
<body>
    <div class="full-bg"></div>
    <div id="bodydiv" style="margin: 0;">
        <div id="contentwrapper" style="padding: 50px;">
            <h1>hello <img src="https://...image.JPEG" style="border-radius: 15px; height: auto; width: 75%;"></h1>
            <!-- 可添加更多内容测试多页效果 -->
        </div>
    </div>
</body>
</html>
`;

const browser = await puppeteer.launch({
    args: args
});
const page = await browser.newPage();
await page.emulateMediaType('print');
await page.setContent(html, {
    waitUntil: 'networkidle0',
});
pdfObj['buffer'] = Buffer.from(Object.values(await page.pdf(options)));

await browser.close(); // 关闭浏览器实例，避免资源泄漏

关键修改说明 #

• @page规则：明确设置页面尺寸为A5、边距0，和Puppeteer的配置保持一致，确保每个页面的基准布局统一
• .full-bg容器：用fixed定位铺满整个视口，z-index: -1确保在内容下方，background-size: cover保证背景适配页面尺寸，repeat属性让背景在多页重复显示
• body样式调整：去掉原有的absolute定位，改用relative避免和固定定位的背景容器冲突，同时清除默认边距和内边距
• 保留printBackground: true：这是Puppeteer生成PDF时渲染背景的关键配置

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