Puppeteer无头模式下PDF截图及元素截图失效问题求助

问题概述 #

• 服务器部署场景下，headless: true模式无法正常截图PDF：方法1访问PDF接口报net::ERR_ABORTED，方法2无报错但截图为空白。
• 无法对PDF页面的特定元素截图，即使在headless: false模式下也失效。

一、解决无头模式PDF截图空白/报错问题 #

无头模式下Chrome默认未启用PDF渲染组件，需添加启动参数开启，同时优化等待逻辑确保PDF完全加载。

修改后的方法1（服务器PDF接口访问） #

const puppeteer = require('puppeteer');

(async function pdf2Img(pdfPath) {
  try {
    const browser = await puppeteer.launch({
      headless: 'new', // 新版无头模式兼容性更好
      args: [
        '--disable-gpu',
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--enable-features=PDFViewer', // 强制启用PDF渲染组件
        '--force-color-profile=srgb'
      ],
      defaultViewport: { width: 1920, height: 1150 }
    });

    const page = await browser.newPage();
    // 拦截请求确保PDF资源正常加载
    await page.setRequestInterception(true);
    page.on('request', (req) => req.continue());

    await page.goto(pdfPath, {
      waitUntil: 'networkidle0', // 等待网络空闲，确保PDF加载完成
      timeout: 60000
    });

    // 等待PDF渲染完成，替代固定sleep
    await page.waitForFunction(() => {
      const embed = document.querySelector('embed');
      return embed && embed.getSVGDocument() !== null;
    }, { timeout: 30000 });

    // 截取整个页面
    await page.screenshot({
      path: 'full-page-pdf.jpeg',
      type: 'jpeg',
      quality: 100
    });

    await browser.close();
  } catch (error) {
    console.error(error.message);
  }
})('http://localhost:5000/file.pdf');

修改后的方法2（本地PDF转Base64嵌入） #

const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');
const hbs = require('handlebars');

function blobToBase64(blob) {
  return fs.readFileSync(blob, 'base64');
}
const readHtmlFromTemplate = function (templateFolder, templateName) {
  const FILE_PATH = path.join(process.cwd(), templateFolder, `${templateName}.hbs`);
  return fs.readFileSync(FILE_PATH, 'utf-8');
};

const bindDataWithHtml = (html, data) => hbs.compile(html)(data);

const base64String = blobToBase64('./file.pdf');

(async function pdf2Img() {
  try {
    const browser = await puppeteer.launch({
      headless: 'new',
      args: [
        '--disable-gpu',
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--enable-features=PDFViewer',
        '--force-color-profile=srgb'
      ],
      defaultViewport: { width: 1920, height: 1150 }
    });
    const page = await browser.newPage();

    const html = readHtmlFromTemplate('invoice-template', 'pdf');
    const htmlContent = bindDataWithHtml(html, {
      pdfDataUrl: `data:application/pdf;base64,${base64String}`
    });

    await page.setContent(htmlContent, {
      waitUntil: 'networkidle0',
      timeout: 60000
    });

    // 等待iframe内PDF加载完成
    const iframe = await page.$('#pdfDoc');
    const frame = await iframe.contentFrame();
    await frame.waitForFunction(() => document.body.innerText.trim() !== '', { timeout: 30000 });

    // 截取iframe元素
    await iframe.screenshot({
      path: 'iframe-pdf.jpeg',
      type: 'jpeg',
      quality: 100
    });

    await browser.close();
  } catch (error) {
    console.error(error.message);
  }
})();

二、解决特定元素截图失效问题 #

核心原因是PDF渲染在embed/iframe的独立上下文，需进入子上下文确认元素状态，或精准计算截取区域。

方案1：进入子上下文获取目标元素 #

仅适用于可选择文本的PDF（非图片式PDF）：

// 接方法1代码，在等待PDF渲染完成后添加：
const embed = await page.$('embed');
const frame = await embed.contentFrame(); // 获取embed的子渲染上下文
const targetElement = await frame.$('#target-element'); // 替换为PDF内实际元素选择器
const boundingBox = await targetElement.boundingBox();

// 截取目标元素
await page.screenshot({
  path: 'specific-element.jpeg',
  type: 'jpeg',
  quality: 100,
  clip: {
    x: boundingBox.x,
    y: boundingBox.y,
    width: boundingBox.width,
    height: boundingBox.height
  }
});

方案2：固定比例计算截取区域 #

适用于图片式PDF（无法选择元素）：

// 接方法1代码，在等待PDF渲染完成后添加：
const pdfDimensions = await page.evaluate(() => {
  const embed = document.querySelector('embed');
  return { width: embed.clientWidth, height: embed.clientHeight };
});

// 自定义截取区域（示例：截取PDF右侧1/3区域）
const clipArea = {
  x: pdfDimensions.width * 2/3,
  y: 0,
  width: pdfDimensions.width * 1/3,
  height: pdfDimensions.height
};

await page.screenshot({
  path: 'custom-area.jpeg',
  type: 'jpeg',
  quality: 100,
  clip: clipArea
});

关键注意事项 #

• 优先使用headless: 'new'替代旧版headless: true，新版功能更接近有头模式。
• 必须添加--enable-features=PDFViewer参数，确保无头模式加载PDF渲染组件。
• 替换固定setTimeout为waitForFunction或networkidle0，避免因加载速度差异导致截图失败。
• 处理iframe/embed内的PDF时，需进入子上下文等待加载，不能仅依赖父页面的DOM就绪事件。

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