Laravel队列在生产服务器无法运行问题排查求助

可能的原因及解决办法 #

1. 队列连接配置未生效 #

• 确认生产环境.env中QUEUE_CONNECTION=database配置正确，执行php artisan config:clear和php artisan config:cache刷新配置，重启队列进程（停止queue:work后重新启动）。
• 检查生产数据库连接权限：确保数据库用户拥有jobs、failed_jobs表的增删改查权限，可通过php artisan tinker测试：

  DB::table('jobs')->get();
  

  若报错则排查数据库权限或连接配置。

2. Job被推送到非默认队列 #

• 检查FetchCdekOrderInfo Job类的$queue属性，若存在protected $queue = 'xxx';，启动队列时需指定对应队列：

  php artisan queue:work --queue=xxx,default
  

• 排查Job分发代码，若使用->onQueue('custom')指定队列，需同步修改queue:work命令的队列参数。

3. Job静默执行失败 #

• 查看Laravel日志文件storage/logs/laravel.log，排查API调用失败、依赖缺失、文件权限等错误。
• 启用失败队列：执行php artisan queue:failed-table和php artisan migrate，启动队列时添加重试参数：

  php artisan queue:work --tries=3
  

  执行php artisan queue:failed查看失败任务详情。

4. 服务器环境差异 #

• 检查PHP版本（Laravel10要求PHP8.0+）及扩展：确保安装curl（快递API调用依赖）、pdo_mysql等必要扩展。
• 核对服务器时区与本地一致，避免因时间差异导致Job延迟执行。

5. Supervisor配置问题 #

• 确认Supervisor配置文件的command路径正确，用户权限为web服务器用户（如www-data），示例配置：

  [program:laravel-queue]
  process_name=%(program_name)s_%(process_num)02d
  command=php /var/www/your-project/artisan queue:work database --queue=default --sleep=3 --tries=3 --timeout=60
  autostart=true
  autorestart=true
  stopasgroup=true
  killasgroup=true
  user=www-data
  numprocs=2
  stdout_logfile=/var/www/your-project/storage/logs/queue.log
  

• 执行以下命令重载生效：

  sudo supervisorctl reread
  sudo supervisorctl update
  sudo supervisorctl restart laravel-queue:*
  

  查看Supervisor日志（通常在/var/log/supervisor/）排查启动错误。

生产环境队列标准配置步骤 #

1. 配置队列连接
   在.env中设置QUEUE_CONNECTION=database，执行php artisan config:cache刷新配置。

2. 迁移队列相关表

   php artisan queue:table
   php artisan queue:failed-table
   php artisan queue:batches-table
   php artisan notifications:table
   php artisan migrate
   

3. 配置进程管理器（Supervisor）
   按上述示例创建Supervisor配置文件，确保队列进程持续运行。

4. 监控与维护

   • 定期查看storage/logs/laravel.log和队列日志；
   • 使用php artisan queue:failed查看失败任务，php artisan queue:retry [id]重试指定任务；
   • 定期清理失败任务：php artisan queue:flush。

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