使用Headless Chrome的--print-to-pdf选项时背景图片不显示的解决方法

问题场景 #

• 在Chrome浏览器界面打开目标HTML文件时，背景图片显示正常；通过浏览器右键打印生成PDF，背景图片也能正常渲染。
• 使用无头模式命令行生成PDF时，背景图片缺失，原命令如下：

chrome --headless --print-to-pdf=test.pdf test.html

解决方案 #

方法1：添加命令行参数 #

修改命令，加入--print-background参数，强制无头模式打印背景内容：

chrome --headless --print-to-pdf=test.pdf --print-background test.html

方法2：添加CSS属性增强兼容性 #

在.leftcolumn的CSS样式中添加-webkit-print-color-adjust: exact;属性，确保浏览器打印时保留背景颜色和图片：

.leftcolumn {
    float: left;
    background-color: rgb(41, 52, 72);
    background-image: url(test.png);
    color: white;
    height: inherit;
    width: 35%;
    padding: 20px;
    -webkit-print-color-adjust: exact;
}

原因说明 #

Chrome无头打印模式默认不会渲染背景图片和颜色，--print-background参数的作用等同于在浏览器界面打印设置中勾选「背景图形」选项；-webkit-print-color-adjust: exact则是通过CSS强制浏览器在打印时精确呈现背景样式，双重保障可以避免不同环境下的渲染差异。

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