使用Puppeteer生成A4尺寸PDF时出现灰色边框及尺寸偏差的问题排查

我明白你现在遇到的问题——明明已经把各种边距、边框都设为0了，用Puppeteer生成的A4 PDF还是带着浅灰边框，甚至尺寸还和标准A4有细微偏差，这确实挺闹心的。咱们一步步来排查解决：

一、先解决灰色边框的问题 #

你的代码里已经做了很多边框、边距的重置，但还是出现灰色边框，最可能的原因是CSS语法错误导致打印样式规则不生效，加上阴影样式的潜在影响：

1. 修正@media print中@page的语法错误
   你当前的@page规则里给height和width加了双引号：

@page {
  height: "297mm";
  width: "210mm";
  margin: 0;
}

CSS属性值不需要双引号，带引号会让浏览器无法识别这个规则，直接忽略，导致页面渲染 fallback 到默认的打印样式，这很可能就是灰色边框的来源。把引号去掉：

@page {
  height: 297mm;
  width: 210mm;
  margin: 0;
}

2. 强制覆盖打印模式下的阴影和边框
   虽然你给.page加了print:shadow-none的Tailwind变体，但有时候Puppeteer的无头模式渲染对变体优先级的处理会有偏差。直接在@media print里强制覆盖：

@media print {
  /* 其他规则... */
  .page {
    box-shadow: none !important;
    outline: none !important;
    border: none !important;
  }
}

3. 排查页面默认样式的残留
   如果上面两步还没解决，可以在page.goto之后，手动注入一段样式来强制重置所有可能的默认样式：

await page.addStyleTag({
  content: `
    * {
      box-sizing: border-box !important;
      border: none !important;
      outline: none !important;
    }
    html, body {
      margin: 0 !important;
      padding: 0 !important;
    }
  `,
});

二、解决尺寸偏差的问题 #

你提到PDF实际尺寸是297.1mm×210.3mm，和标准A4有细微偏差，主要和Puppeteer的无头模式版本、PDF配置与CSS规则的冲突有关：

1. 切换到新的无头模式
   旧的headless: true模式是基于旧版Chrome的渲染引擎，和真实浏览器的打印行为有差异。换成Puppeteer推荐的新无头模式：

browser = await puppeteer.launch({
  headless: "new", // 替换原来的headless: true
  args: ["--no-sandbox", "--disable-setuid-sandbox"],
});

2. 统一PDF配置与CSS规则
   你当前同时在page.pdf里指定了height和width，又在CSS里设了@page的尺寸，还开启了preferCSSPageSize: true，容易出现规则冲突。建议删掉page.pdf里的height和width，完全依赖CSS的@page规则：

const pdfBuffer = await page.pdf({
  margin: { top: 0, right: 0, bottom: 0, left: 0 },
  printBackground: true,
  preferCSSPageSize: true, // 优先使用CSS定义的页面尺寸
});

3. 验证预览页面的结构
   检查你的预览页面（http://localhost:3000/en/invoice/preview2）里，.page元素是否真的严格贴合210mm×297mm，有没有父元素带额外的padding或margin，导致整体尺寸被撑大。

三、额外的排查小技巧 #

• 先关闭Puppeteer的无头模式（headless: false），打开可视化的Chrome，手动打印预览，看是否也有灰色边框和尺寸偏差：如果手动打印也有，那问题肯定在CSS；如果手动没问题，那就是Puppeteer的配置问题。
• 检查Tailwind CSS v4的print变体是否正确生效，有时候框架的变体优先级可能不如直接写的@media print规则。

按照上面的步骤修改后，应该就能解决灰色边框和尺寸偏差的问题了。

内容来源于stack exchange