使用Puppeteer生成HTML转PDF时，如何避免Div内容分页？

我之前在使用Puppeteer + Headless Chrome生成PDF时，也碰到过page-break-inside: avoid完全不生效的坑！折腾了好一阵才找到几个靠谱的解决方案，分享给你：

1. 改用更现代的CSS Fragmentation属性 #

传统的page-break-inside: avoid在Chrome的打印/PDF渲染引擎里有时候会被忽略，尤其是当元素使用了flex、grid这类现代布局时。试试同时添加标准的break-inside: avoid属性，并且用!important强制覆盖可能的样式冲突：

.no-break {
  page-break-inside: avoid !important;
  break-inside: avoid !important; /* 现代浏览器优先识别这个 */
  display: block !important; /* 强制元素为块级，避免布局干扰 */
}

把这个类加到你不想被分页的<div>上，比如：

<div class="no-break">
  <!-- 这里的内容不会被分页拆分 -->
</div>

2. 检查并调整父元素的布局样式 #

如果需要避免分页的元素是flex/grid容器的子元素，父容器的布局规则可能会打断分页逻辑。这时候可以把需要保护的内容单独包裹在一个带有.no-break类的块级元素里，脱离原来的flex/grid上下文：

<!-- 原来的flex容器 -->
<div class="flex-container">
  <!-- 包裹需要避免分页的内容 -->
  <div class="no-break">
    <div class="flex-item">...</div>
    <div class="flex-item">...</div>
  </div>
</div>

3. 优化Puppeteer的PDF生成配置 #

调整PDF生成选项，确保浏览器以正确的模式渲染页面：

async function createListenPdf(html) {
  try {
    var jobId = uuidv4();
    const browser = await puppeteer.launch({ 
      headless: 'new', // 推荐使用新版无头模式，渲染更稳定
      args: ['--no-sandbox', '--disable-setuid-sandbox'] // 避免环境权限问题
    });
    const page = await browser.newPage();
    
    // 等待页面完全加载后再生成PDF，确保样式和内容都渲染完成
    await page.setContent(html, { waitUntil: 'networkidle0' });
    
    const pdfBuffer = await page.pdf({
      format: 'A4',
      printBackground: true, // 确保背景样式被渲染
      margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
      preferCSSPageSize: true // 优先使用CSS中定义的页面尺寸
    });
    
    await browser.close();
    return pdfBuffer;
  } catch (error) {
    console.error('PDF生成失败:', error);
    throw error;
  }
}

4. 排查元素高度问题 #

如果需要避免分页的元素高度超过了单页PDF的高度，page-break-inside: avoid自然不会生效——浏览器不可能把一个超过单页高度的内容强行放在一页里。这时候需要调整内容，比如拆分元素或者缩小内容尺寸。

额外注意事项 #

• 避免给需要保护的元素或其父元素设置overflow: hidden，这个属性也会干扰分页规则。
• 检查页面中是否有其他CSS规则（比如媒体查询@media print）覆盖了你的分页样式。

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