根本原因是模型未实现searchable接口或tosearchablearray()返回空数组；需确认使用use searchable;、数据存在、配置正确、队列启用（或设scout_queue=false）、排除软删除影响，并检查类自动加载与环境依赖。
为什么 php artisan scout:import 没反应，数据没进 Algolia/Elasticsearch？
根本原因通常是模型没实现 Searchable 接口，或者 toSearchableArray() 返回了空数组。Laravel Scout 不会自动扫描字段，它只索引你明确返回的数据。
- 确认模型用了
use Searchable;trait，且数据库表里有对应记录（Scout 只导入已存在的数据） - 检查
toSearchableArray()是否过滤掉了全部字段，比如写了return [];或误判了$this->name为 null - 运行命令前先试下
AppModelsPost::search('test')->get()，如果直接报错AlgoliaAlgoliaSearchExceptionsUnreachableHostException，说明配置的SCOUT_DRIVER和对应服务（如 Algolia 的ALGOLIA_APP_ID）不匹配或网络不通 - 本地用
mysql驱动调试时，别忘了php artisan config:clear—— Scout 会缓存驱动配置，改了.env不清缓存就还是老行为
search() 查不到刚 save() 的数据？同步时机不对
默认情况下，Scout 是「异步」更新索引的，靠队列触发。如果你没开队列监听，save() 后立刻 search()，查到的就是旧快照。
- 开发阶段最简单：把
SCOUT_QUEUE设为false，强制同步写入，避免等待队列消费 - 生产环境必须开队列，但要确保
queue:work进程活着，且失败任务进了failed_jobs表——用php artisan queue:failed看有没有卡住的索引任务 - 临时补救：手动调
$post->searchable()强制同步单条，比等队列更快 - 注意软删除：如果模型用了
SoftDeletes，默认不会被索引（Scout 跳过trashed()记录），需要显式加withTrashed()或重写shouldBeSearchable()
搜索结果排序乱、相关性差，where() 和 orderBy() 不能混用
Scout 的 where() 是在搜索引擎里做的过滤，orderBy() 却是 Laravel 从搜索结果里取 ID 后再查 MySQL 排序——两者根本不在一个层面，强行组合会导致分页错乱、性能崩塌。
- 想按数据库字段排序（如
created_at），别用orderBy()，改用搜索引擎原生排序：Algolia 用customRanking配置，Meilisearch 用sortableAttributes，Elasticsearch 得写body参数传 DSL -
where('status', 1)可以，但where('price', '>', 100)在 Algolia 上不生效（不支持数值范围查询），得换 Meilisearch 或自己写filter字符串 - 相关性调优优先改
searchableAs()返回的索引名，然后在对应搜索引擎后台设 synonym、ranking rules，别指望 PHP 层硬凑
部署后 scout:import 报 Class 'App\Models\Post' not found
不是类名写错，而是 Composer 自动加载没刷新，尤其在容器或无交互环境里，autoload_classmap.php 没更新。
- 上线脚本里必须加
composer dump-autoload --optimize（或--classmap-authoritative），否则 Scout 找不到模型类 - 如果用了 Docker，确认
vendor/没被 .dockerignore 掉，且artisan命令运行在正确 PHP 版本的容器里（常见于多版本共存时调错 CLI） - 某些 PaaS（如 Laravel Vapor）会剥离 dev 依赖，但
scout:import在部署时执行，需确保laravel/scout在require而非require-dev
Scout 的坑基本都藏在「配置和运行环境的错位」里：本地跑得通的 config/scout.php，换到服务器可能因扩展缺失（如 ext-curl）、权限限制（写不了 storage/logs/）或 DNS 解析失败而静默失败。动手前先 php -m | grep curl 和 curl -I https://your-algolia.app-id.algolianet.com 看一眼，比翻文档快。
