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; } 在浏览器里看着正常，但导出 PDF 后变成纯白底。
- 根本原因不是 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和 base64background-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 或层叠覆盖。
