HTML转PDF换背景技巧分享

一分耕耘，一分收获！既然都打开这篇《HTML转PDF换背景方法详解》，就坚持看下去，学下去吧！本文主要会给大家讲到等等知识点，如果大家对本文有好的建议或者看到有不足之处，非常欢迎大家积极提出！在后续文章我会继续更新文章相关的内容，希望对大家都有所帮助！

HTML转PDF时背景不显示是因为浏览器默认禁用背景打印，需在Puppeteer中设printBackground:true、wkhtmltopdf加--background参数、WeasyPrint则原生支持background-color和base64图片。

HTML 转 PDF 时“换背景”通常不是指 PDF 自身有背景色（PDF 标准不支持页面级背景色），而是指：在 HTML 中设置的 background-color 或 background-image 能否正常出现在生成的 PDF 里。答案是——默认多数工具会忽略背景，必须显式开启打印背景选项。

为什么 HTML 的 background-color 在 PDF 里不显示？

这是浏览器打印机制的默认行为：出于节省墨水/纸张考虑，Chrome、Edge、Firefox 等默认禁用背景图形（包括 background-color 和 background-image）。PDF 导出若基于浏览器打印（如 window.print()、Puppeteer 的 page.pdf() 默认配置），就会继承该限制。

常见现象：

body { background-color: #f0f9ff; }

• 根本原因不是 CSS 写错了，而是渲染引擎主动丢弃了背景绘制指令
• Puppeteer、wkhtmltopdf、WeasyPrint 等工具行为各不相同，不能一概而论
• 即使开启背景，background-image 的 base64 或相对路径可能因资源加载失败而空白

puppeteer 中启用背景并导出 PDF

使用 Puppeteer 时，必须在 page.pdf() 的 printBackground 选项设为 true，否则所有背景均被忽略。

await page.pdf({
  path: 'output.pdf',
  format: 'A4',
  printBackground: true  // ⚠️ 必须显式设置
});

• printBackground: true 是唯一开关，没有其他替代参数
• 若 HTML 中用了 background-image: url('./bg.png')，确保路径可被 Puppeteer 加载（推荐绝对路径或 base64 内联）
• 避免使用 background-attachment: fixed，Puppeteer 渲染时可能错位或失效
• 测试时先用 page.screenshot() 看是否显示背景，再导 PDF —— 截图不显示，PDF 一定也不显示

wkhtmltopdf 怎么让背景生效？

wkhtmltopdf 默认同样禁用背景，需加 --enable-local-file-access（如果背景图是本地文件）和 --background 参数。

wkhtmltopdf --background --enable-local-file-access input.html output.pdf

• --background 是关键，缺它就无背景
• 若背景图是网络地址（如 https://...），通常无需 --enable-local-file-access
• 遇到字体或 SVG 背景不渲染？可能是 wkhtmltopdf 版本太老（建议 ≥ 0.12.6），或缺少系统字体支持
• 不支持 CSS 变量（var(--bg)）作为 background 值，需预编译为具体颜色

WeasyPrint 对 background 的兼容性细节

WeasyPrint 是纯 Python 渲染引擎，对 CSS 支持较好，但仍有边界：

• 支持 background-color 和 base64 background-image，无需额外开关
• 不支持 background-blend-mode、background-clip: text 等较新特性
• 若用 url("bg.jpg")，路径必须相对于当前工作目录，或用 file:// 绝对路径
• 注意：WeasyPrint 默认将 视为内容容器，若想全页铺底色，建议写在 @page 规则里（但仅支持 background-color，不支持图片）：

  @page { background-color: #fff8e1; }

真正容易被忽略的是：不同工具对「背景」的理解粒度不同——有的只认 body 或 html 元素的背景，有的要求父容器 height: 100% 才能撑满；还有些 PDF 阅读器（如 macOS 预览）默认关闭“显示背景图形”，导致你以为没导出成功，其实是阅读器没开。动手前，先确认你用的是哪个工具、版本号多少、背景写在哪个元素上、有没有被 !important 或层叠覆盖。

好了，本文到此结束，带大家了解了《HTML转PDF换背景技巧分享》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！