Puppeteer生成PDF时页眉页脚异常问题咨询

这是版本升级后的行为变更，并非Bug，需要调整代码适配新规则。

核心问题原因 #

Puppeteer 10.x及以上版本修改了PDF页眉页脚的渲染逻辑：

• 仅设置单个模板（header或footer）时，未设置的模板区域会自动填充默认内容（页眉默认显示日期，页脚默认显示页面URL和页码）
• 同时设置两个模板但未正确配置时，可能因模板结构问题导致内容不显示

代码调整方案 #

1. 必须同时显式声明headerTemplate和footerTemplate，哪怕其中一个是空字符串（<span></span>）
2. 确保开启displayHeaderFooter: true，这是启用页眉页脚的前提
3. 预留足够的margin边距（top和bottom），避免模板内容被页面主体裁剪
4. 模板中使用官方指定的类名占位符（如pageNumber、totalPages、date）来插入动态内容

修正后的可复现代码 #

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent('<h1>测试PDF内容</h1>');

  // 仅显示页脚的配置
  const pdfOptions = {
    displayHeaderFooter: true,
    headerTemplate: '<span></span>', // 显式设置空页眉模板，避免默认日期显示
    footerTemplate: '<div style="font-size:12px; text-align:center; width:100%;">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</div>',
    margin: { top: '40px', bottom: '40px' } // 预留边距显示页脚
  };

  await page.pdf({ ...pdfOptions, path: 'test-footer.pdf' });

  // 仅显示页眉的配置
  const headerOnlyOptions = {
    displayHeaderFooter: true,
    headerTemplate: '<div style="font-size:12px; text-align:right; width:100%;">生成日期：<span class="date"></span></div>',
    footerTemplate: '<span></span>', // 显式设置空页脚模板，避免默认URL和页码显示
    margin: { top: '40px', bottom: '40px' }
  };

  await page.pdf({ ...headerOnlyOptions, path: 'test-header.pdf' });

  await browser.close();
})();

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