Laravel Scout + Meilisearch 是最轻量、响应最快且不依赖 MySQL 全文索引的方案，需确保 Meilisearch 服务就绪、.env 与 config/scout.php 配置一致、toSearchableArray() 返回非空数组且字段设为 searchable，并验证数据已真实写入索引。
直接用 Laravel Scout + Meilisearch 是目前最轻量、响应最快、且完全不依赖 MySQL 全文索引的方案。它把分词、拼音容错、typo 纠正全交给 Meilisearch，你只需确保三件事对齐：服务连得上、配置写得对、数据真进去了。
Meilisearch 服务启动与连通性验证
Scout 不会启动或管理 Meilisearch 进程，这步必须手动搞定。本地开发最稳的方式是 Docker：
docker run -d -p 7700:7700 -v $(pwd)/data:/data.ms getmeili/meilisearch:v1.10
然后立刻验证连通性：
curl http://127.0.0.1:7700/health
返回 {"status":"available"} 才算就绪。常见失败点：
- 用 WSL 或 Laravel Sail 时，
MEILISEARCH_HOST不能写127.0.0.1，得换成host.docker.internal或宿主机 IP - Laravel Sail 用户注意：
MEILISEARCH_HOST应为http://meilisearch:7700（容器名） - 生产环境别硬编码
127.0.0.1，用域名或负载均衡地址，并确认防火墙放行 7700 端口
SCOUT_DRIVER 和 config/scout.php 配置一致性
驱动开关和连接参数必须同时生效，缺一不可。检查 .env 是否包含：
SCOUT_DRIVER=meilisearch MEILISEARCH_HOST=http://127.0.0.1:7700 MEILISEARCH_KEY=masterKey
注意：Meilisearch v1.0+ 默认密钥是 masterKey，不是空字符串。同时确保 config/scout.php 中的 meilisearch 键存在且未被注释：
'meilisearch' => [
'host' => env('MEILISEARCH_HOST', 'http://127.0.0.1:7700'),
'key' => env('MEILISEARCH_KEY', 'masterKey'),
]
改完 .env 后务必执行：
php artisan config:clear
否则缓存旧配置，连错地址也不报错。
toSearchableArray() 返回非空数组且字段可搜索
Scout 不自动索引全部字段，toSearchableArray() 是唯一控制入口。禁止返回 [] 或 null，必须是非空数组。常见问题：
- 字段名拼错（如写成
titile）、含对象（如Carbon实例）、含未预加载的关联属性，都会导致索引失败或结果为空 - 时间字段建议转成
timestamp或格式化字符串：$this->published_at->timestamp - 中文搜索需确保字段在 Meilisearch 后台被标记为
searchable，例如手动 PATCH：curl -X PATCH 'http://localhost:7700/indexes/articles/settings' -H 'Content-Type: application/json' -d '{"searchableAttributes": ["title", "content"]}'
导入后搜不到？先查索引里有没有
scout:import 命令只负责把数据推过去，不校验是否成功写入。很多“搜不到”问题其实出在索引本身没建好。手动查索引内容（以 articles 索引为例）：
curl 'http://localhost:7700/indexes/articles/search' -d '{"q":"laravel"}'
如果返回空或 "nbHits": 0，说明数据根本没进索引——优先检查 toSearchableArray() 输出、日志是否有异常、以及 Meilisearch 是否启用了正确的 locales（v1.8+ 中文默认支持，旧版需显式设 "language": ["zh"]）。
