Laravel Scout + Elasticsearch 返回空结果主因是索引未同步，需手动执行 scout:import；改过 toSearchableArray() 要先 flush 再 import；ES 7.x+ 动态映射禁用易致写入失败；高亮需绕过 Scout 直调 ES 客户端并复现查询结构；搜索缓存应归一化关键词、缓存稳定字段、设短时效。
为什么直接用 Laravel Scout + Elasticsearch 会返回空结果？
常见现象是 Searchable 模型调用 search() 后始终没数据，连 toArray() 都为空。根本原因不是代码写错，而是 Elasticsearch 的索引没真正同步——Laravel Scout 默认只在模型事件（如 saved）触发时推数据，但新建索引后历史数据不会自动导入。
- 必须手动执行
php artisan scout:import "App\Models\Post"才能把现有数据写入 ES - 如果改过模型的
toSearchableArray()，要先php artisan scout:flush "App\Models\Post"再重新 import - Elasticsearch 7.x+ 默认禁用动态映射（
dynamic: false），而 Scout 的默认 mapping 可能字段类型不匹配，导致写入失败但无提示——检查 ES 日志里的mapper_parsing_exception
如何让搜索联想返回带高亮的关键词片段？
原生 search() 不支持高亮，得绕过 Scout 直接调用 Elasticsearch PHP Client。关键不是“怎么加高亮”，而是“怎么保持 Scout 的查询逻辑一致”——比如你用 where('status', 1) 过滤，那高亮请求也得复现同样的 bool query 结构。
- 用
MatchPhrasePrefixQuery替代MatchQuery，更适合联想场景（输入“larav”能命中 “laravel”） - 高亮字段必须在 mapping 中显式开启：
"highlight": {"fields": {"title": {}}} - 返回结果里
highlight是个数组，同名字段可能有多个片段，别直接取[0]，要用implode('…', $hit['_highlight']['title'] ?? [])
前端输入 debounce 后，后端如何避免重复查 Elasticsearch？
用户狂敲键盘时，同一关键词可能发 5 次请求，Elasticsearch 虽快，但并发打满也会拖慢响应。Laravel 自带的缓存机制在这里容易误伤——比如用 Cache::remember() 缓存 60 秒，但用户刚输完“php”，又删掉改成“pyt”，两个 key 实际语义接近，却算作不同缓存项。
- 对搜索词做简单归一化：转小写、去首尾空格、限制最大长度（如
substr(strtolower(trim($q)), 0, 20)） - 不要缓存原始 ES 响应体（含 timestamp 等动态字段），只缓存
['id', 'title', 'url']这类稳定字段 - 缓存时间设短些（5–10 秒），比长缓存更安全；ES 查询本身延迟通常
部署后发现联想结果顺序乱、相关性差
本地开发时看着正常，上线后 ES 返回结果排序像随机——大概率是集群配置差异。Elasticsearch 默认按 _score 降序，但 score 计算依赖 index.refresh_interval 和分片数，生产环境若用了多节点、冷热分离或自定义 routing，score 就不可靠。
- 强制指定排序字段：在 search query 里加
"sort": [{"updated_at": {"order": "desc"}}]，别依赖默认 score - 如果真要靠相关性，确认所有节点用相同分析器（analyzer），尤其中文要用
ik_smart而非默认standard - 别在 Laravel 模型里用
orderBy('score')——ES 返回的_score在hits数组里，不在 Eloquent 属性中
ES 的 mapping 定义和查询 DSL 是紧耦合的，改一个字段类型，不重建索引就上线，后面所有联想都会渐进式失效。这点比数据库迁移还脆，得养成每次改 schema 就跑一遍 flush + import 的习惯。
