DomPDF本地与服务器渲染效果不一致，寻求解决方案

这种本地正常、服务器翻车的情况在DomPDF开发里太常见了，我整理了几个高频排查方向，你可以逐一验证：

• 字体缺失或加载异常
  本地大概率用了系统自带的字体（比如Windows的微软雅黑、Mac的苹方），但服务器是Linux系统的话，默认没有这些字体，DomPDF会自动 fallback 到内置的替代字体，直接打乱排版。
  解决办法：把信头用到的字体文件（.ttf/.otf格式）放到项目静态资源目录，用@font-face在CSS里明确声明，确保路径在服务器上能正确访问。示例代码：

  @font-face {
      font-family: 'CustomHeaderFont';
      src: url('./fonts/your-font-file.ttf') format('truetype');
      font-weight: 600;
      font-style: normal;
  }
  .header {
      font-family: 'CustomHeaderFont', sans-serif;
  }
  

  另外要确认服务器上DomPDF的字体缓存目录有写入权限，不然字体无法被正确加载缓存。

• 资源路径不匹配
  本地开发时的相对路径（比如./images/header-logo.png），到了服务器可能因为项目部署的根目录不同、虚拟主机配置差异，导致资源找不到。
  解决办法：用基于项目根目录的绝对路径，或者用PHP动态生成路径，比如：

  $logoPath = realpath(__DIR__ . '/../public/images/header-logo.png');
  

  避免直接写相对路径，确保服务器能准确定位到图片、CSS等资源。

• PHP环境与依赖差异
  本地和服务器的PHP版本、扩展可能不一样，比如DomPDF 2.x要求PHP 7.1以上，服务器如果用了更低版本，或者缺少gd、mbstring、dom这些必要扩展，都会导致渲染异常。
  解决办法：对比本地和服务器的PHP版本，检查服务器是否安装了DomPDF要求的所有扩展；同时确保Composer依赖在服务器上完整安装，不要遗漏任何包。

• CSS兼容性问题
  DomPDF对CSS的支持和浏览器有差距，一些在浏览器里正常的布局（比如复杂的Flex、Grid，或者某些定位属性），在DomPDF里可能解析不一致。
  解决办法：简化信头的CSS写法，优先用DomPDF支持更好的属性——比如用表格布局代替Flex，避免使用position: absolute的复杂嵌套；可以参考DomPDF官方文档的CSS支持列表，排查是否有属性被忽略。

• 缓存与权限问题
  服务器可能缓存了旧的PDF或静态资源，导致新修改没生效；另外DomPDF的临时目录、字体缓存目录如果没有写入权限，也会导致渲染失败。
  解决办法：清除服务器的OPcache、应用缓存，给静态资源加版本号（比如style.css?v=20240520）强制刷新；检查服务器上storage或DomPDF指定的临时目录权限，确保PHP进程能读写。

• DomPDF配置不一致
  本地和服务器的DomPDF配置参数可能不同，比如isRemoteEnabled（是否允许加载远程资源）、defaultPaperSize、dpi这些，都会影响最终渲染效果。
  解决办法：把本地的DomPDF配置同步到服务器，比如如果信头用了远程图片，要开启isRemoteEnabled = true；确保纸张尺寸、DPI等参数和本地一致。

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