应安装algolia/algoliasearch-client-php:^4（PHP≥8.1），避免混用旧命名空间，按用途分实例使用Admin Key（索引管理）和Search-Only Key（搜索），并确认索引名大小写及数据同步完成。
Composer 安装 algolia/algoliasearch-client-php 时提示版本冲突
直接运行 composer require algolia/algoliasearch-client-php 很可能失败，尤其在 PHP 8.1+ 或 Laravel 10+ 项目中。官方库从 v4 开始要求 PHP ≥ 8.1，且已弃用旧版 algoliasearch/algoliasearch-client-php（v1/v2），后者早已停止维护并无法连接新 Algolia 应用。
确认当前环境 PHP 版本：php -v；若低于 8.1，必须升级 PHP 或降级客户端——但不推荐降级，因 Algolia 已关闭对旧 API key 的兼容支持。
- PHP 8.1+：安装最新稳定版
algolia/algoliasearch-client-php:^4 - PHP 7.4–8.0：只能用
algolia/algoliasearch-client-php:^3.5，但需手动配置host为'https://<your_app_id>-dsn.algolia.net'</your_app_id>（非默认algolia.net） - 避免混用
algoliasearch/...和algolia/...命名空间， Composer 会报 autoload 冲突
初始化 Client 时抛出 “Invalid application ID or API key” 错误
这不是密钥写错那么简单。Algolia v4 SDK 默认使用 Admin API Key 初始化 Client，但实际业务中应严格区分 Admin Key（仅用于索引管理）和 Search-Only API Key（前端或无权操作索引的场景）。用 Admin Key 初始化后调用 search() 不报错，但用 Search-Only Key 初始化后调用 setSettings() 就会触发该错误。
正确做法是：按用途分实例。
立即学习“PHP免费学习笔记（深入）”；
- 管理索引（创建、更新 schema、批量导入）：用 Admin Key 实例 ——
$adminClient = new \Algolia\AlgoliaSearch\Client('<app_id>', '<admin_api_key>');</admin_api_key></app_id> - 执行搜索请求：用 Search-Only Key 实例 ——
$searchClient = new \Algolia\AlgoliaSearch\Client('<app_id>', '<search_only_api_key>');</search_only_api_key></app_id> - Key 必须从 Algolia Dashboard 的 API Keys 页面复制，不能从 “Credentials” 卡片里抄错字段（常见把 Application ID 当成 API Key）
调用 search() 返回空结果或 hits 为 []，但 Dashboard 明显有数据
最常被忽略的是索引名称拼写大小写敏感，以及未确认数据是否真正推送到线上索引。Algolia 的索引名区分大小写，'products' 和 'Products' 是两个完全不同的索引。
- 检查索引是否存在：用 Admin Client 调用
$adminClient->listIndices()，确认返回列表含目标索引名 - 确认数据已成功同步：执行一次
$index->saveObjects([...])后，务必等待返回的taskID通过$index->waitTask($taskID)完成，否则搜索时数据尚未生效 - 搜索时未指定
attributesToRetrieve，导致返回对象为空字段 —— 默认只返回 objectID 和 _highlightResult，如需全部字段要显式传参：$index->search('query', ['attributesToRetrieve' => ['*']])
在 Laravel 中集成时 Query Builder 风格 API 不可用
Algolia 官方 PHP SDK 没有提供类似 Eloquent 的链式查询语法。所谓“Laravel Scout 集成”本质是 Scout 封装了 Algolia Client，但 Scout v10+ 已移除对 Algolia 的原生支持（需额外装 laravel/scout-algolia-engine），且该扩展包长期未更新，与 Algolia v4 不兼容。
如果你坚持用 Scout，目前唯一可靠路径是绕过它，直接用原生 Client：
- 在
app/Services/AlgoliaSearchService.php中封装常用操作，例如searchProducts(string $q, array $filters = []) - 避免在 Controller 中直连 Client，防止密钥泄露或重复初始化
- 注意 Laravel 的队列任务中使用 Client 时，需确保
ALGOLIA_APP_ID和ALGOLIA_SEARCH_KEY已注入到 env 并被队列 worker 加载（常见漏掉php artisan config:clear）
Algolia 的核心动作——建索引、设规则、搜词——全靠参数驱动，没捷径。最容易卡住的地方不是语法，而是没看清文档里每个选项的生效层级（index-level 还是 app-level）和缓存行为。
