scout + algolia 在 laravel 中搜不到数据，主因是未同步软删除模型、未配置 $fillable 或 searchableas()、未显式定义 tosearchablearray() 字段，且 algolia 配置错误或索引残留；中文需预处理切词并配置 searchableattributes。
为什么 Scout + Algolia 在 Laravel 里容易搜不到数据？
默认情况下，php artisan scout:import 不会自动同步软删除（softDeletes）模型，也不会处理未设置 $fillable 或未启用 searchableAs() 的索引名。常见现象是：数据库有数据，Algolia 后台控制台显示空索引，或搜索返回空数组。
- 确认模型已实现
Searchable接口，并在toSearchableArray()中显式返回字段（不要依赖默认的toArray()，它可能含敏感字段或关系数据） - 检查
config/scout.php中algolia配置是否填了正确的id和secret（注意不是 API Key），且driver已设为'algolia' - 运行
php artisan scout:flush "App\Models\Post"清空旧索引后再重导，避免残留脏数据干扰 - 如果用队列导入，确保
QUEUE_CONNECTION=sync临时关闭队列调试，否则失败日志可能被吞掉
如何让 Algolia 支持中文分词和模糊匹配？
Algolia 原生不支持中文分词，但可通过预处理字段 + 配置策略绕过。关键不是改 Algolia，而是改你塞进去的数据结构和索引设置。
- 在
toSearchableArray()中对中文字段做简单切词（比如按字、按常见词组拆解），例如：'title_tokens' => preg_split('/(?title)，再把title_tokens加入可搜索字段 - 在 Algolia 控制台的 Index Settings → Ranking → Custom ranking 中添加
desc(popularity)或自定义数值字段，提升相关性 - 搜索时强制开启模糊：调用
search('关键词', ['advancedSyntax' => true, 'typoTolerance' => 'strict'])；'minWordSizefor1Typo'设为2可让两字词也容错 - 避免在
searchableOn()中只写['title']，应扩展为['title', 'title_tokens', 'content']提高命中率
Scout 搜索结果怎么关联 Eloquent 关系（比如作者、分类）？
Scout 返回的是原始 Algolia 记录（数组），不是 Eloquent 实例，所以不能直接调用 ->author。必须手动补关联，且要注意 N+1 问题。
- 在
toSearchableArray()中预先存好关联 ID 和必要字段，例如：'author_id' => $this->author_id, 'author_name' => $this->author?->name - 搜索后用
map()构造临时对象，或用with()预加载：先收集所有author_id，再一次性查User::whereIn('id', $ids)->pluck('name', 'id')，最后合并到结果中 - 不要在循环里对每个结果调
Author::find()—— 这会触发 N+1 查询，哪怕用了 Scout，数据库压力仍在 - 如果需要完整模型实例，用
pluck('id')拿到 ID 列表，再走Post::with('author', 'category')->findMany($ids)，这是最稳妥的回查方式
上线后搜索突然变慢或报 AlgoliaException？
多数情况不是 Scout 慢，而是 Algolia 请求被限频、证书校验失败，或环境变量没生效。本地跑得通，线上挂掉，90% 出在配置和网络层。
- 检查
.env是否真被加载：在控制器里dd(config('scout.algolia.id'))，别只信php artisan config:cache—— 它可能缓存了旧值 - 生产环境禁用
APP_DEBUG=true后，Algolia 错误会被静默吞掉；加try/catch包裹search()并记录$e->getMessage()，常见错误如"Index not found"表明索引名拼错或未创建 - Cloudflare 或反向代理可能拦截 POST 请求（Algolia 搜索是 POST），确认服务器能直连
https://your-app-id-dsn.algolia.net（用curl -v测试） - Algolia 免费版有 10K 操作/月限制，超限后返回 403；监控
scout:status输出或 Algolia 后台 Usage Dashboard
