Spatie/laravel-pdf路由浏览器访问失败但CLI执行正常

问题背景 #

我在部署了OpenLiteSpeed、PHP8.2及nvm管理Node.js的远程Ubuntu 22.04服务器上，使用spatie/laravel-pdf生成PDF时遇到异常：

• 本地Ubuntu环境下，访问/test-pdf路由可正常生成并保存测试PDF，核心代码如下：

  Route::get('/test-pdf', function () {
      $htmlContent = "<h1>Hello World!</h1><p>This is a test PDF generated from HTML.</p>";
      $pdfPath = public_path('hello_world.pdf');
  
      Pdf::html($htmlContent)
          ->withBrowsershot(function ($browsershot) {
              $browsershot 
                  ->setIncludePath('$PATH:'.config('browsershot.include_path')); // 适配nvm的路径配置
          }) 
          ->save($pdfPath);
          
      return 'PDF generated and saved to ' . $pdfPath;
  });
  

• 远程服务器上，浏览器访问该路由时报错：

  Error: Failed to launch the browser process!
  
  TROUBLESHOOTING: https://pptr.dev/troubleshooting
  

• 已尝试Puppeteer官方排障方案无效，但以Laravel项目虚拟主机的执行用户身份从CLI运行时，该路由可正常生成PDF。

可能原因及解决方案 #

1. 环境变量差异（PATH与nvm路径） #

CLI执行时会加载用户shell配置文件（如~/.bashrc、~/.profile），而OpenLiteSpeed运行PHP时的环境变量是精简的，可能未包含nvm管理的Node.js路径，导致找不到Puppeteer依赖的Chrome/Chromium二进制文件。

解决方法：

• 直接在代码中指定完整的Node.js和Chrome路径，不依赖环境变量：

  Pdf::html($htmlContent)
      ->withBrowsershot(function ($browsershot) {
          // 替换为服务器上nvm下node的实际路径，例如/home/xxx/.nvm/versions/node/v20.x.x/bin/node
          $browsershot->setNodeBinary('/your/node/path/bin/node')
                      // 替换为Puppeteer安装的Chrome路径，可通过`npm list puppeteer`定位，例如node_modules/puppeteer/.local-chromium/linux-xxxx/chrome-linux/chrome
                      ->setChromeBinary('/your/chrome/path');
      })
      ->save($pdfPath);
  

• 或在OpenLiteSpeed虚拟主机配置中添加环境变量：
  在虚拟主机的Environment设置里，添加PATH=/home/xxx/.nvm/versions/node/v20.x.x/bin:$PATH，确保Node和Chrome路径被识别。

2. 权限问题 #

浏览器请求时，OpenLiteSpeed运行的用户（通常是nobody或虚拟主机指定用户）可能没有权限访问Puppeteer临时目录、Chrome安装目录，或无法写入PDF保存目录（如public目录）。

解决方法：

• 检查并调整public目录权限：

  sudo chown -R your-web-user:your-web-user /path/to/laravel/public
  sudo chmod -R 755 /path/to/laravel/public
  

• 指定可读写的自定义临时目录给Puppeteer：

  Pdf::html($htmlContent)
      ->withBrowsershot(function ($browsershot) {
          $browsershot->setTempDir('/path/to/writable/tmp-dir');
      })
      ->save($pdfPath);
  

3. 无头浏览器依赖缺失 #

CLI环境可能加载了更多系统配置，而OpenLiteSpeed运行环境缺少Chrome无头模式所需的系统依赖（如字体库、共享库）。

解决方法：
安装Chrome无头模式所需的依赖包：

sudo apt-get install -y libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxi6 libxtst6 libnss3 libcups2 libxss1 libxrandr2 libasound2 libatk1.0-0 libatk-bridge2.0-0 libpangocairo-1.0-0 libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-0 libgtk-3-0 libgbm1 libdrm2 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0

4. OpenLiteSpeed进程资源限制 #

OpenLiteSpeed对PHP进程的内存、文件描述符等资源限制，可能导致Chrome无法启动。

解决方法：

• 在OpenLiteSpeed的Server Configuration > Tuning中，提高Max Connections、Memory Soft Limit、Memory Hard Limit的值；
• 在虚拟主机的PHP Settings里，调整memory_limit、max_execution_time等参数，确保有足够资源运行Chrome。

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