最常见原因是模型未正确实现toSearchableArray()或遗漏Searchable trait；需显式定义索引字段、配置attributesForFaceting、启用中文分词、清除并重缓存配置。
Algolia 配置后搜索没返回结果，scout:import 执行了但索引为空
最常见原因是模型没正确实现 toSearchableArray() 或漏掉了 Searchable trait。Algolia 不会自动同步数据库字段，必须显式定义要索引的字段。
检查点：
- 模型是否用了
use Searchable;（注意不是use Laravel\Scout\Searchable;，Laravel 10+ 已改用全局 trait） -
toSearchableArray()返回的数组不能含 Eloquent 关系对象或未转为数组的集合，否则 Algolia 会静默跳过该记录 - 执行
php artisan scout:import "App\Models\Post"后，立刻去 Algolia Dashboard 的 Indices 页面查看对应 index 的 record count，别只信终端输出 - 如果用的是 Algolia 的免费 plan，注意它默认启用「Typo tolerance」和「Attribute ranking」，可能让完全匹配的关键词排在后面——临时调试时可在 Dashboard 的 index 设置里关掉「Typo tolerance」
搜索时 where() 条件不生效，比如 Post::search('xxx')->where('status', 'published')->get()
Scout 的 where() 在 Algolia 驱动下只支持「过滤器（facet filters）」，且要求对应字段在 Algolia index 中被声明为 attributesForFaceting，否则直接忽略，不报错也不过滤。
解决方式：
- 在模型中添加
public $scoutMetadata = ['status' => ['type' => 'string']];（仅 Laravel 11+ 支持；旧版需手动在 Algolia Dashboard 设置attributesForFaceting） - 或者更稳妥：重写
toSearchableArray()，确保status字段存在且值为字符串（如'published'），再在 Dashboard 的 index → Configuration → Attributes for faceting 中添加status - 注意
where()不支持 like、in_array 等复杂条件，只支持等值匹配和布尔值；想查范围要用whereBetween()，且字段类型得是 number
中文搜索完全不匹配，输入“文章”搜不出标题含“文章”的记录
Algolia 默认分词策略针对英文，对中文基本无效——它不会自动按字或词切分，而是把整个字段当一个 token 处理。
必须手动配置中文支持：
- 进入 Algolia Dashboard → Index → Configuration → Language → 勾选
Chinese（不是 “Simplified Chinese”，就选Chinese） - 同时开启
decompounded attributes，并填入需要中文分词的字段名，例如title, content - 改完配置后，必须重新导入数据：
php artisan scout:flush "App\Models\Post"+php artisan scout:import "App\Models\Post"，光刷新配置不行 - 验证方法：在 Dashboard 的 index → Search preview 中输入单个汉字（如“文”），看是否能命中含“文章”的记录
生产环境部署后搜索 403 或 422，错误信息是 "message": "Invalid Application-ID or API-Key"
不是密钥写错了，大概率是 .env 里的 ALGOLIA_APP_ID 和 ALGOLIA_API_KEY 没生效——Scout 默认读取 config/scout.php，而这个文件在部署时往往被缓存，且不会自动重载 .env 变量。
关键动作：
- 运行
php artisan config:clear，再php artisan config:cache（注意顺序，先清再缓） - 确认
config/scout.php中'algolia' => [...]里的app_id和secret是通过env()读取的，不是硬编码 - Algolia 的 Admin API Key 绝对不能暴露给前端或浏览器端代码；如果用了 Algolia 的 JavaScript SDK，务必单独配一个 Search-Only API Key，并限制 referer
Algolia 的索引结构和分词逻辑跟数据库查询完全不同，很多“理所当然”的行为（比如模糊前缀、字段级权重、空格分隔）都需要在 Dashboard 里显式开关和调参，别指望配置完就自动像 MySQL 一样工作。
