本文详解在 CodeIgniter 3 项目中使用 Dompdf（v3.0.0+）渲染带背景图片的 PDF 时的关键配置，重点解决 background-image 不显示的问题，涵盖 CSS 语法、路径处理、base path 设置及兼容性注意事项。
本文详解在 codeigniter 3 项目中使用 dompdf（v3.0.0+）渲染带背景图片的 pdf 时的关键配置，重点解决 `background-image` 不显示的问题，涵盖 css 语法、路径处理、base path 设置及兼容性注意事项。
在使用 Dompdf 生成 PDF 时，为页面添加背景图片是一个常见需求，但因 Dompdf 对 CSS 的支持有限（尤其对 background-image 的解析较严格），常出现图片不显示的问题。根本原因在于：Dompdf 要求背景图片必须通过标准 CSS url() 函数声明，且路径需可被 Dompdf 实际定位到——而原代码中错误地将 PHP 函数 base_url() 直接写入 CSS 属性值，导致生成无效 CSS。
✅ 正确写法：使用 url() + 绝对文件系统路径（推荐）
Dompdf 不解析 PHP 函数（如 base_url() 或 site_url()），它只接收纯 HTML/CSS 字符串。因此，背景图片路径应指向服务器上的真实物理路径（非 URL），并包裹在 url() 中：
public function index() {
$dompdf = new Dompdf\Dompdf();
// ✅ 关键修正：使用 realpath() 构建绝对路径，并用 url() 包裹
$bg_path = realpath(FCPATH . 'uploads/background_images/CoverImage1.jpg');
$html = '
<html>
<head>
<style>
@page { margin: 0; }
body {
margin: 0;
padding: 20px;
background-image: url("' . $bg_path . '");
background-size: cover; /* 防止重复平铺，全屏覆盖 */
background-position: center;
background-repeat: no-repeat; /* 强制不重复 */
font-family: sans-serif;
}
</style>
</head>
<body>
<h2>Background Image</h2>
<p style="color:red; text-shadow: 1px 1px 2px rgba(0,0,0,0.3);">
Background image is now visible and properly scaled.
</p>
</body>
</html>
';
$dompdf->loadHtml($html);
// ✅ 必须设置 base path（用于解析相对路径中的资源）
$dompdf->setBasePath(FCPATH);
// 可选：提升渲染质量（尤其对图片）
$dompdf->setOptions(['isRemoteEnabled' => true]);
$dompdf->render();
$dompdf->stream("document_with_background.pdf", ["Attachment" => false]);
}⚠️ 注意事项与最佳实践
-
路径必须是绝对路径：
url()中的路径需为服务器上可读取的完整文件路径（如/var/www/html/uploads/...），不能是 Web URL（如https://example.com/uploads/...），除非启用isRemoteEnabled并确保网络可达。 -
setBasePath()的作用：它仅影响 Dompdf 解析 HTML 中<img src="..." alt="如何使用 Dompdf 在 PDF 中正确添加背景图片" >或 CSS 中url(...)的相对路径。若你已传入绝对路径（如realpath(...)），setBasePath()非必需，但仍建议保留以兼容其他资源。 -
CSS 兼容性限制：
- Dompdf v3.x 支持
background-size: cover和no-repeat，但不支持background-attachment: fixed或 CSS Grid 背景定位高级特性。 - 建议始终显式声明
background-repeat: no-repeat和background-size: cover/contain，避免默认平铺造成视觉混乱。
- Dompdf v3.x 支持
-
图片格式与权限：确保图片为 JPG/PNG 等 Dompdf 支持格式，且 Web 服务器用户（如
www-data）有读取该文件的权限。 -
调试技巧：临时将
$html输出到浏览器查看源码，确认路径字符串是否拼接正确；或先用file_exists($bg_path)验证路径有效性。
✅ 总结
Dompdf 渲染背景图片失败，90% 源于路径错误或 CSS 语法不规范。牢记三要素：
① 使用 background-image: url("绝对文件路径");；
② 用 realpath() 获取真实路径，而非 base_url()；
③ 合理设置 background-* 相关属性控制显示效果。
遵循以上方法，即可稳定在 CodeIgniter 3 + Dompdf 项目中生成带高质量背景图的 PDF 文档。
