Laravel队列调用Dompdf转换多行列含图片表格时超时问题

问题核心 #

• 基于PHP+Dompdf的脚本：从数据库拉取X条数据，生成包含X行表格+X张本地图片的PDF
• X≤9时运行正常；X=18时，命令行执行完全正常（耗时1-1.5分钟，峰值内存<30M），但放入Laravel队列后持续超时

已尝试的无效操作 #

• 调整任务timeout至900s、队列retry_after至1800s
• 按Dompdf文档启用OPcache并设置opcache.memory_consumption=512

服务器环境 #

• Ubuntu 24.04
• PHP 8.3
• Laravel v12.56
• dompdf v3.1.5
• 备注：相同逻辑脚本在Laravel v6 + PHP v7.4环境下可正常处理X=18的场景，升级后失效

替代方案（Browsershot）的问题 #

• 转换速度略快，但生成的PDF未完全遵循CSS样式，无法渲染页码
• 队列调用时抛出异常，错误信息如下：

[2026-05-10 00:11:09] production.ERROR: The command "PATH=$PATH:/usr/local/bin:/opt/homebrew/bin NODE_PATH=`npm root -g`  "node" 'vendor/spatie/browsershot/src/../bin/browser.cjs' '{"url":"file:\/\/\/tmp\/>

Exit Code: 127(Command not found)

Working directory: /

Output:
================

Error Output:
================
sh: 1: npm: not found
sh: 1: node: not found
 {"exception":"[object] (Symfony\\Component\\Process\\Exception\\ProcessFailedException(code: 0): The command \"PATH=$PATH:/usr/local/bin:/opt/homebrew/bin NODE_PATH=`npm root -g`  \"node\" 'vendor/spatie/>

解决方向指引 #

针对Dompdf队列超时问题 #

1. 排查队列与命令行的环境差异
   • 对比队列进程和命令行的PHP配置：检查max_execution_time、memory_limit、OPcache状态（队列进程可能未加载OPcache），可在队列任务中输出phpinfo()到日志做对比
   • 确认队列进程的运行用户是否有读取本地图片的权限，避免因权限阻塞导致超时
2. 细化任务性能监控
   • 在队列任务中添加分步日志：记录拉取数据、组装HTML、加载图片、Dompdf渲染PDF每一步的内存占用和耗时，定位具体瓶颈环节
3. 验证Laravel队列配置有效性
   • 确认队列驱动（如Redis/数据库）的retry_after配置已生效，部分驱动需重启队列进程才能加载新配置
   • 检查进程管理器（如Supervisor）的超时设置，是否存在比Laravel配置更严格的进程中断规则
4. Dompdf版本与兼容性测试
   • 尝试降级Dompdf至v2.x版本，验证是否为v3.x与PHP8.3/Laravel12的兼容性问题
   • 检查HTML/CSS写法：新版本Dompdf对复杂选择器、未优化的表格布局可能存在性能损耗，尝试简化样式逻辑

针对Browsershot的异常问题 #

1. 补充Node.js环境依赖
   • 通过apt install nodejs npm安装服务器缺失的Node.js和npm
   • 在代码中指定Node二进制文件路径，避免环境变量问题：

     Browsershot::html($html)->setNodeBinary('/usr/bin/node');
     

2. 修复样式与页码渲染
   • 使用Chrome兼容的CSS分页规则，比如通过@page定义页边距，配合showHeaderFooter()方法配置页码：

     Browsershot::html($html)
         ->showHeaderFooter()
         ->headerHtml('<div style="text-align:right; padding-right:20px;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>')
         ->setOption('margin.top', '2cm');
     

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