Scout不生效首要检查SCOUT_DRIVER配置是否正确且与已安装扩展匹配，修改.env后须运行php artisan config:clear；模型需启用Searchable并确保同步时机正确，索引数据需手动验证，搜索排序需依赖引擎原生能力而非Laravel的orderBy。
Scout 没生效？先确认 SCOUT_DRIVER 配置对不对
Scout 不工作，八成是驱动没配好。Laravel 默认不启用任何搜索引擎，.env 里必须显式指定驱动，且值要和已安装的扩展匹配。
常见错误现象：Call to undefined method App\Models\Post::search() 或搜索始终返回空数组，其实根本没走 Scout 流程。
-
SCOUT_DRIVER=meilisearch：需已装meilisearch/meilisearch-php和本地/远程 MeiliSearch 服务 -
SCOUT_DRIVER=algolia：需配置ALGOLIA_APP_ID和ALGOLIA_SECRET -
SCOUT_DRIVER=null（默认值）＝完全不索引、不搜索，不是“模拟模式”
改完 .env 别忘了运行 php artisan config:clear，缓存不刷新，改了也白改。
模型加了 Searchable 还搜不到？检查索引同步时机
Scout 不会自动监听所有增删改——它只在模型调用 save()、create()、delete() 等 Eloquent 方法时触发同步，但前提是模型启用了观察者。
使用场景：后台批量导入数据、用 DB::table()->insert() 直接写库、或队列中处理模型但未显式触发同步。
- 批量操作后补索引：
php artisan scout:import "App\Models\Post" - 强制单条同步：
$post->searchable()（新增/更新后）或$post->unsearchable()（删除前） - 队列环境务必确认
SCOUT_QUEUE=true，否则异步任务可能被丢弃
注意：searchable() 不会重复建索引，但也不会校验字段是否变更；字段改了但没调这个方法，线上数据就和索引对不上。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
search() 返回空？别急着查代码，先看索引里有没有数据
Scout 的 search() 是纯客户端查询，结果为空 ≠ 逻辑错，很可能是索引压根没数据，或者字段根本没进索引。
性能影响：MeiliSearch/Algolia 本身响应快，但如果你在 toSearchableArray() 里做了 N+1 查询，每次索引都会拖慢写入，还可能导致部分文档缺失。
- 手动查索引内容（以 MeiliSearch 为例）：
curl 'http://localhost:7700/indexes/posts/search' -d '{"q":"laravel"}' - 检查模型是否重写了
toSearchableArray()，漏掉了关键字段，比如只返回['title']却想搜content - 中文搜索需额外配置：MeiliSearch 要开
"searchableAttributes": ["title", "content"]并确保分词器支持中文（v1.8+ 默认支持，旧版需设"locales": ["zh"]）
Scout 本身不处理分词逻辑，它只是把请求原样转发给底层引擎——引擎不认中文，你就永远搜不到。
搜索结果排序乱、相关性差？where() 和 orderBy() 别混用
Scout 的 search() 返回的是引擎原生结果，orderBy() 在 Scout 层无效，强行加只会静默忽略。想按数据库字段排序（比如按发布时间），得用 raw() 或换策略。
容易踩的坑：用 ->where('status', 1)->orderBy('created_at', 'desc')，以为能链式调用，实际 orderBy 根本不生效，返回顺序由引擎打分决定。
- MeiliSearch 自定义排序：
search('laravel')->raw(['sort': ['created_at:desc']]) - Algolia：
search('laravel')->with(['facetFilters' => ['status:1'], 'sortFacetValuesBy' => 'count']) - 纯数据库 fallback：先
search()拿 ID 列表，再whereIn('id', $ids)->orderBy(...)查库（适合小数据量）
相关性调优不在 Laravel 层，而在搜索引擎配置里——比如 MeiliSearch 的 rankingRules，改错了会导致所有关键词都排不准，不是改两行 PHP 就能解决的事。
