本文详解如何通过 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 完全支持）。
以下为完整可运行示例：
Nano Pdf
使用 nano-pdf CLI 通过自然语言指令编辑 PDF 文件。
下载
⚠️ 关键注意事项
emulateMediaType('print') 不可省略
：若仍用 'screen'，所有 @media print 样式将被忽略，分页失效；
避免内联样式干扰
：break-before 需在
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: 'new' });
const [page] = await browser.pages();
const htmlContent = `
Heading 1 Page 1
This is content for page 1.
Heading 2 Page 2
This is content for page 2.
Heading 3 Page 3
This is content for page 3.
`;
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.');
})();