开启队列后Laravel Scout+Meilisearch+Redis导入失败求助

架构老林

2026-6-26

解决Laravel Scout队列模式下提示未安装Meilisearch客户端的问题

重启队列Worker进程
队列Worker启动时会缓存依赖环境，如果你是先启动Worker再安装的Meilisearch客户端，Worker进程无法读取到新安装的依赖。先彻底重启Worker：
```
sail php artisan queue:restart
# 之后重新启动Redis队列Worker
sail php artisan queue:work redis
```
同时可以进入容器验证依赖是否存在：
```
sail shell
composer show meilisearch/meilisearch-php
```
如果没有输出，说明容器内依赖未同步，执行sail composer install重新安装依赖。
清除配置与缓存
缓存的配置可能导致队列环境下无法正确读取Scout或Meilisearch的设置，执行以下命令清理：
```
sail php artisan config:clear
sail php artisan cache:clear
sail php artisan scout:flush "App\Models\Persona"
```
清理完成后重新执行导入命令：
```
sail php artisan scout:import "App\Models\Persona"
```
更新Composer自动加载
自动加载文件过期可能导致Worker找不到Meilisearch客户端类，执行：
```
sail composer dump-autoload
```
排查失败任务的详细异常
通过以下命令查看失败任务的完整堆栈信息，定位具体问题：
```
# 列出所有失败任务
sail php artisan queue:failed
# 查看单个失败任务的详情，替换[任务ID]为实际ID
sail php artisan queue:show [任务ID]
```
重点检查是否真的是类找不到，还是Meilisearch的连接配置（如MEILISEARCH_HOST、MEILISEARCH_KEY）在队列环境下未正确加载。
验证Scout队列配置
确认.env文件中SCOUT_QUEUE=true，且队列连接QUEUE_CONNECTION=redis，确保Scout使用的队列和你启动的Worker是同一个连接渠道。同时检查Persona模型的searchableUsing方法，确保引擎实例化逻辑在队列环境下能正确获取Meilisearch客户端。