1. Puppeteer与PDF生成基础
Puppeteer是Google Chrome团队维护的一个Node库，它提供了高级API来控制无头版Chrome或Chromium。想象一下，你有一个看不见的浏览器，可以按照你的指令自动完成各种操作，这就是Puppeteer的核心能力。在PDF生成领域，Puppeteer最大的优势在于它能完美还原网页的样式和布局，就像你在浏览器中看到的那样。
安装Puppeteer非常简单，只需要一个npm命令：
npm install puppeteer基础PDF生成代码只需要几行：
const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await page.pdf({ path: 'example.pdf' }); await browser.close(); })();这个基础示例虽然简单，但已经包含了PDF生成的核心流程：启动浏览器→创建新页面→加载内容→生成PDF→关闭浏览器。实际项目中，我们会遇到各种复杂需求，比如自定义封面、页眉页脚、特殊分页等，这些都需要更深入的Puppeteer技巧。
2. 项目结构与模板设计
一个典型的PDF生成项目应该包含清晰的文件结构。建议采用如下组织方式：
project/ ├── templates/ # HTML模板目录 │ └── report.html # 主模板文件 ├── assets/ # 静态资源 │ ├── css/ # 样式表 │ └── images/ # 图片资源 ├── config/ # 配置文件 │ └── pdf.config.js # PDF生成配置 └── generators/ # 生成器脚本 └── pdf-generator.js # 主生成逻辑HTML模板设计是PDF质量的关键。一个好的模板应该考虑：
- 响应式布局，确保在不同尺寸下都能正确显示
- 明确的分页控制，使用CSS的page-break属性
- 合理的字体选择，优先使用系统字体或嵌入字体
- 适当的边距设置，避免内容被裁剪
封面页的特殊处理：
<div class="cover-page"> <h1>报告标题</h1> <div class="meta"> <p>生成日期：{{date}}</p> <p>作者：{{author}}</p> </div> </div> <style> .cover-page { width: 794px; /* A4纸宽度 */ height: 1123px; /* A4纸高度 */ page-break-after: always; /* 确保封面独占一页 */ } </style>3. 常见问题与解决方案
3.1 资源加载问题
当使用本地文件生成PDF时，最常见的三个问题是CSS不加载、背景不显示和图片缺失。这些问题通常是因为路径解析不正确导致的。
解决方案一：使用绝对路径
await page.goto(`file://${path.resolve('template.html')}`);解决方案二：直接注入内容
// 注入CSS await page.addStyleTag({ path: 'assets/css/style.css' }); // 注入图片 const imageBuffer = fs.readFileSync('assets/images/logo.png'); const imageBase64 = imageBuffer.toString('base64'); await page.evaluate((base64) => { document.querySelector('#logo').src = `data:image/png;base64,${base64}`; }, imageBase64);3.2 背景与颜色打印
默认情况下，浏览器打印时会忽略背景色和背景图片以节省墨水。要强制打印背景，需要两个关键配置：
await page.pdf({ printBackground: true, preferCSSPageSize: true, margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' } });此外，在CSS中需要添加：
@media print { body { -webkit-print-color-adjust: exact !important; print-color-adjust: exact !important; } }3.3 页眉页脚定制
Puppeteer允许通过headerTemplate和footerTemplate参数自定义页眉页脚：
const footerTemplate = ` <div style="width:100%;font-size:10px;text-align:center;"> 第<span class="pageNumber"></span>页/共<span class="totalPages"></span>页 </div>`; await page.pdf({ displayHeaderFooter: true, footerTemplate, margin: { top: '80px', bottom: '80px' } });特殊页处理（如封面不显示页眉页脚）：
await page.addStyleTag({ content: ` @page :first { margin-top: 0; } .cover-page { margin-top: 0 !important; } ` });4. 高级技巧与性能优化
4.1 多PDF合并技术
对于复杂文档，建议分部分生成再合并。pdf-lib是目前最活跃的PDF操作库：
const { PDFDocument } = require('pdf-lib'); async function mergePDFs(pdfBuffers) { const mergedPdf = await PDFDocument.create(); for (const buffer of pdfBuffers) { const pdf = await PDFDocument.load(buffer); const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices()); pages.forEach(page => mergedPdf.addPage(page)); } return await mergedPdf.save(); }4.2 字体嵌入处理
确保PDF中正确显示自定义字体：
@font-face { font-family: 'CustomFont'; src: url('assets/fonts/custom.woff2') format('woff2'); font-display: swap; } body { font-family: 'CustomFont', sans-serif; }4.3 性能优化建议
- 复用浏览器实例：不要为每个PDF都启动新浏览器
// 全局维护一个浏览器实例 let globalBrowser; async function getBrowser() { if (!globalBrowser) { globalBrowser = await puppeteer.launch(); } return globalBrowser; }- 并行处理：使用Promise.all处理多个页面
const pagePromises = urls.map(async url => { const page = await browser.newPage(); await page.goto(url); return page.pdf(); }); const pdfBuffers = await Promise.all(pagePromises);- 内存管理：适当设置启动参数
puppeteer.launch({ args: [ '--disable-dev-shm-usage', '--no-sandbox', '--disable-setuid-sandbox', '--disable-accelerated-2d-canvas', '--disable-gpu' ] });5. 实战案例：企业报告生成系统
让我们通过一个完整的案例来整合前面介绍的技术。假设我们需要为一个电商平台生成月度销售报告PDF，包含：
- 定制封面
- 目录页（自动生成）
- 多章节内容
- 动态图表
- 公司页脚
5.1 系统架构设计
report-system/ ├── api/ # 数据接口 ├── templates/ # 模板引擎 ├── services/ # 业务逻辑 │ └── pdf-service.js # PDF生成服务 └── public/ # 输出目录5.2 核心生成逻辑
async function generateReport(data) { const browser = await puppeteer.launch(); const page = await browser.newPage(); // 渲染封面 const coverHtml = await renderTemplate('cover', data); await page.setContent(coverHtml); const coverPdf = await page.pdf({ margin: { top: 0, right: 0, bottom: 0, left: 0 } }); // 渲染内容页 const contentHtml = await renderTemplate('content', data); await page.setContent(contentHtml); const contentPdf = await page.pdf({ displayHeaderFooter: true, footerTemplate: getFooterTemplate(), margin: { top: '2cm', bottom: '2cm' } }); // 合并PDF const mergedPdf = await mergePDFs([coverPdf, contentPdf]); await browser.close(); return mergedPdf; }5.3 动态图表处理
对于数据可视化图表，推荐两种方案：
方案一：使用Chart.js等前端库
// 在模板中预留canvas <canvas id="salesChart" width="800" height="400"></canvas> // 注入渲染脚本 await page.evaluate(data => { const ctx = document.getElementById('salesChart').getContext('2d'); new Chart(ctx, { type: 'bar', data: data.chartData }); }, reportData);方案二：服务端生成图表图片
// 使用node-canvas等服务端绘图库生成图表 const chartImage = await generateChartImage(reportData.chartData); // 注入到模板 await page.evaluate(imageData => { document.getElementById('chart-placeholder').src = imageData; }, chartImage);6. 调试技巧与最佳实践
6.1 常见问题排查
内容截断问题：
- 检查CSS中的box-sizing设置
- 确认没有固定高度的容器
- 使用@media print查询优化打印样式
字体不一致：
- 确保所有字体都正确嵌入
- 提供fallback字体栈
- 测试不同操作系统下的表现
性能瓶颈：
- 使用headless: 'new'参数启用新版无头模式
- 限制并发PDF生成数量
- 监控内存使用情况
6.2 调试技巧
- 可视化调试（禁用无头模式）：
const browser = await puppeteer.launch({ headless: false });- 生成截图辅助调试：
await page.screenshot({ path: 'debug.png', fullPage: true });- 打印控制台日志：
page.on('console', msg => console.log('PAGE LOG:', msg.text()));6.3 企业级部署建议
- 使用Docker容器化：
FROM node:16 WORKDIR /app COPY package*.json ./ RUN npm install COPY . . CMD ["node", "server.js"]- 配置资源限制：
const browser = await puppeteer.launch({ executablePath: '/usr/bin/chromium-browser', args: [ '--disable-dev-shm-usage', '--no-sandbox', '--disable-setuid-sandbox', '--memory-pressure-off', '--disable-accelerated-2d-canvas' ] });- 实现队列处理：
const Queue = require('bull'); const pdfQueue = new Queue('pdf generation'); pdfQueue.process(async job => { return generatePDF(job.data); });
