捕获 Elasticsearch\Exception\ClientResponseException 并判断 getCode() === 404 可精准处理索引不存在异常；需避免宽泛捕获 Exception，生产环境应通过发布命令建索引而非运行时自动创建。
ES 查询时报 index_not_found_exception 怎么捕获
直接 try-catch Elasticsearch\Exception\ClientResponseException 就行，这是客户端抛出的最常见异常类型。ES 8.x 返回 404 时不会让请求静默失败，而是明确抛这个异常，不处理就会变成 500。
常见错误现象：调用 $client->search() 时索引还没建、被误删或拼错名字（比如写成 posts 但实际是 post_index），日志里看到 "type":"index_not_found_exception"，接口直接崩。
- 必须 catch
ClientResponseException，别只 catchException——它太宽泛，掩盖真实问题 - 检查
$e->getTrace()[0]['file']能快速定位哪行代码触发了查询 - 用
$e->getCode() === 404做精确判断，避免把 503 或 400 当成索引缺失 - 不要在 catch 块里直接
return response()->json(...)，应抛出自定义业务异常，交给全局Handler统一格式化
怎么让 Laravel 自动创建缺失的索引
Scout 不会自动建索引，scout:import 前必须确保索引存在且 mapping 正确。不能依赖“查不到就自动建”，那会把部署问题拖到运行时。
使用场景：CI/CD 部署新版本时，ES 索引结构变了（比如加了中文分词字段），但旧索引还在，新数据同步失败。
- 在
App\Providers\AppServiceProvider::boot()里调用$client->indices()->create()，但仅限开发环境（app()->environment('local')） - 生产环境必须走发布流程：先用
php artisan es:create-index命令建好索引，再跑scout:import - 索引名必须全小写，
PostsIndex这种命名会报invalid_index_name_exception - mapping 中显式声明
"dynamic": false，防止字段意外新增导致查询异常
Scout 模型搜索时索引不存在的兜底逻辑
模型用了 Searchable trait，但对应 ES 索引不存在，Model::search() 会直接抛 ClientResponseException，不会返回空集合。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
性能影响：每次搜索都做 exists 检查（$client->indices()->exists()）会多一次网络往返，QPS 高时明显拖慢响应。
- 不要在
search()前加 exists 判断——那是防御性编程，不是解决方案 - 真正该做的是：部署脚本里确保索引和模型 mapping 一致；监控告警里加入「索引存活检查」任务
- 如果非要运行时兼容，重写模型的
toSearchableArray()，在其中 throw 新异常（如SearchIndexMissingException），比捕获原始客户端异常更语义清晰 -
scout:import失败时默认静默跳过，务必加--force和日志输出，否则根本不知道索引没推上去
为什么 try/catch 捕获不到中间件里的 ES 异常
因为中间件执行在路由匹配之前，而 Scout 的搜索逻辑通常在控制器里，但如果把 ES 查询提前放到中间件（比如权限校验查 ES 白名单），异常会绕过 Laravel 的 Handler 流程。
容易踩的坑：中间件里写 try { $client->search(...) } catch (ClientResponseException $e) { abort(404); }，结果 404 页面渲染失败，前端收到 HTML 而不是 JSON。
- 中间件中必须主动构造 API 响应：
return response()->json(['error' => 'index missing'], 404); - 别依赖
abort()，它走的是视图渲染路径，对 API 请求不适用 - 所有 ES 相关中间件应放在
$middlewareGroups['api']里，避免和 Web 中间件混用 - 若用队列异步同步索引，
unsearchable()调用失败也会抛同样异常，需单独监听SearchableDeleted事件做补偿
ES 索引不存在不是偶发错误，而是部署链路上的确定性缺口。捕获异常只是止损，真正要盯住的是 CI 流程里索引创建、mapping 校验、scout 导入三步是否原子化成功——漏掉任意一环，线上就等着收 500 报警。
