如何使用 Puppeteer 将 HTML 内容精确分页输出到 PDF-js教程-PHP中文网

如何使用 Puppeteer 将 HTML 内容精确分页输出到 PDF

本文详解如何通过 CSS 分页控制属性（如 break-before）配合 Puppeteer 的 emulateMediaType('print')，实现 HTML 中指定元素强制分页渲染为独立 PDF 页面。

本文详解如何通过 css 分页控制属性（如 `break-before`）配合 puppeteer 的 `emulatemediatype('print')`，实现 html 中指定元素强制分页渲染为独立 pdf 页面。

在使用 Puppeteer 生成 PDF 报告时，若需将 HTML 中不同区块（如章节标题、报表模块）严格分配至独立 PDF 页面，仅依赖默认布局是不够的。关键在于利用 CSS 分页媒体查询与标准分页属性，并确保 Puppeteer 正确模拟打印上下文。

✅ 核心方案：CSS @media print + break-before

Puppeteer 的 PDF 生成基于 Chromium 的打印引擎，因此必须启用 page.emulateMediaType('print')（而非 'screen'），否则 @media print 规则不会生效。同时，推荐使用现代 CSS 分页属性 break-before: page（替代已废弃的 page-break-before），它语义清晰、兼容性良好（Chromium ≥ 88 完全支持）。

以下为完整可运行示例：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: 'new' });
  const [page] = await browser.pages();

  const htmlContent = `
    
    
      
        <meta charset="UTF-8"><style>
          @media print {
            /* 每个 h1 前强制分页 */
            h1 {
              break-before: page;
              /* 可选：避免孤行，提升排版健壮性 */
              orphans: 2;
              widows: 2;
            }
            /* 清除默认页边距干扰（尤其当使用 displayHeaderFooter 时） */
            body {
              margin: 0;
              padding: 20px;
            }
          }
        </style><h1>Heading 1 Page 1</h1>
        <p>This is content for page 1.</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill10828" title="财经HTML高端海报生成"><img
														src="https://img.php.cn/upload/skill/000/000/081/179336525482166.jpg" alt="财经HTML高端海报生成" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill10828" title="财经HTML高端海报生成" class="overflowclass">财经HTML高端海报生成</a>
													<p class="overflowclass">复杂得财经如何变成清晰，适合手机看的海报？如何加上你的IP</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill10828" title="财经HTML高端海报生成" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>

        <h1>Heading 2 Page 2</h1>
        <p>This is content for page 2.</p>

        <h1>Heading 3 Page 3</h1>
        <p>This is content for page 3.</p>
      
    
  `;

  await page.setContent(htmlContent, { waitUntil: 'networkidle0' });
  await page.emulateMediaType('print'); // ⚠️ 必须设置为 'print'

  await page.pdf({
    path: 'report.pdf',
    format: 'A4',
    displayHeaderFooter: true,
    margin: {
      top: '140px',   // 为页眉预留空间
      bottom: '100px', // 为页脚预留空间
      left: '10px',
      right: '10px'
    }
  });

  await browser.close();
  console.log('PDF generated with forced page breaks.');
})();

⚠️ 关键注意事项

emulateMediaType('print') 不可省略：若仍用 'screen'，所有 @media print 样式将被忽略，分页失效；
避免内联样式干扰：break-before 需在
页眉/页脚与分页的协同：displayHeaderFooter: true 会自动添加页眉页脚区域，此时 margin.top/bottom 应大于默认页眉页脚高度（通常 ≥ 60px），否则内容可能被遮挡；
内容高度不足时的处理：若某页内容过少，可添加 min-height: 100vh 到或容器，确保单页占满 A4 高度（需配合 @media print）；
调试技巧：临时将 headless: 'new' 改为 headless: false，并在 page.setContent() 后调用 await page.screenshot({path: 'debug.png'})，直观验证分页样式是否正确应用。