DomPDF 项目中 CSS 和图片加载失效的解决方案

问题现象分析

在使用 DomPDF 生成 PDF 文档时，开发者经常遇到 CSS 样式和外部图片无法正确加载的问题。这种情况在不同环境下表现各异：

1. 本地开发环境：通常工作正常，CSS 和图片都能正确渲染
2. 测试环境：CSS 可能正常工作，但图片无法加载
3. 生产环境：CSS 和图片可能都无法正确显示

根本原因探究

1. 路径解析问题

Dompdf 在处理资源路径时，特别是在使用构建工具（如 Vite）的项目中，开发环境和生产环境的资源路径可能不同。Vite 在开发模式下会生成特殊的 URL，而在生产模式下则使用静态资源路径。

2. 远程资源限制

Dompdf 默认出于安全考虑会禁用远程资源的加载。这包括：

• 外部 CSS 文件
• 外部图片（通过 HTTP/HTTPS 加载的图片）
• 外部字体等资源

3. HTTPS 协议问题

某些服务器环境下，HTTPS 协议的资源可能无法加载，而 HTTP 协议的资源可以正常工作，这与服务器的 SSL/TLS 配置或 Dompdf 的 SSL 验证设置有关。

解决方案

1. 启用远程资源

在初始化 Dompdf 时，必须显式启用远程资源加载：

$dompdf = new Dompdf();
$dompdf->set_option('isRemoteEnabled', true);

对于 Laravel-Dompdf 包装器，可以通过配置选项实现：

$pdf = PDF::loadView('your.view');
$pdf->setOption(['isRemoteEnabled' => true]);

2. 处理构建工具路径

对于使用 Vite 等构建工具的项目：

1. 确保生产环境构建后的静态资源路径正确
2. 避免直接使用开发模式的资源路径
3. 考虑使用绝对路径而非相对路径

3. 图片加载优化

• 对于外部图片，确保 URL 可公开访问
• 考虑将图片转换为 base64 编码内联到 HTML 中
• 检查服务器防火墙是否阻止了 Dompdf 对外部资源的请求

4. HTTPS 资源处理

如果 HTTPS 资源无法加载：

1. 检查服务器的 OpenSSL 配置
2. 尝试临时关闭 SSL 验证（仅限开发环境）
3. 考虑将 HTTPS 资源下载到本地后使用

最佳实践建议

1. 环境一致性：尽量保持开发、测试和生产环境的配置一致
2. 资源本地化：将关键 CSS 和图片资源本地化，减少外部依赖
3. 错误排查：启用 Dompdf 的调试日志，查看具体的资源加载错误
4. 缓存处理：生产环境中注意处理静态资源缓存问题

通过以上方法，可以解决大多数 Dompdf 中 CSS 和图片加载失败的问题，确保 PDF 生成的一致性和可靠性。