Laravel 全文检索实战：用 Scout 集成 Algolia 的配置、导入与避坑

当业务里的数据量涨到几十万、上百万后，单靠数据库索引和 SQL 优化，搜索体验往往还是不够理想。本文按 Laravel 5.5 的实际接入顺序，整理 Scout 集成 Algolia 的关键步骤，同时补上导入阶段最常见的超时处理方法，帮助你判断这套毫秒级搜索方案在自己项目里是否值得采用。

先完成依赖安装和账号准备

这套方案的核心是 Laravel Scout 负责对接搜索驱动，Algolia 提供远程全文检索能力。开始之前，先把两个必需依赖装好：

composer require laravel/scout
composer require algolia/algoliasearch-client-php

接着前往 Algolia 官网注册账号，初次使用可以直接选免费版。在账户后台的 API Keys 菜单里，需要记下两个配置项：

• Application ID
• Admin API Key

后续 Laravel 配置和索引导入都会用到这两个值。

配置 Scout 并切换到 Algolia 驱动

安装完成后，先在 config/app.php 的 providers 数组中注册服务提供者：

// Scout全文搜索
LaravelScoutScoutServiceProvider::class,

然后执行发布命令，生成 Scout 的配置文件：

php artisan vendor:publish --provider="LaravelScoutScoutServiceProvider"

命令执行后，会生成 config/scout.php。接下来打开 .env，把驱动和 Algolia 凭据补齐：

# scout配置
SCOUT_DRIVER=algolia
SCOUT_PREFIX=
# algolia的Application ID
ALGOLIA_APP_ID=xxxxxxxxxx
# algolia的Admin API Key
ALGOLIA_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx

这里最关键的是 SCOUT_DRIVER=algolia，它决定 Scout 后续把索引写到 Algolia，而不是走其他搜索驱动。

定义可搜索模型并创建索引

配置完成后，下一步是让具体模型具备可搜索能力。文中的示例模型是 app/Student.php。在测试前，建议先把数据表和测试数据准备好，可以手动执行 SQL，也可以使用 Laravel 的迁移和填充方式批量生成。

模型代码如下：

<?php
namespace App;

use IlluminateDatabaseEloquentModel;

use LaravelScoutSearchable;

/**
 * 学生模型
 */
class Student extends Model
{
    use Searchable;

    /**
     * 索引名称
     *
     * @return string
     */
    public function searchableAs()
    {
        return 'students_index';
    }

    /**
     * 可搜索的数据索引
     *
     * @return array
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();

        // Customize array...

        return $array;
    }
}

这段代码里有两个重点：

searchableAs() 用来指定索引名

这里返回的是 students_index，也就是数据最终会进入 Algolia 后台中的这个索引。

toSearchableArray() 决定哪些字段进入搜索引擎

示例里直接使用了模型的全部数组数据。如果你的表字段很多，或者只希望姓名、学号、班级等部分字段可检索，就可以在这里单独裁剪和重组。

批量导入数据时，最常见的问题是连接超时

模型准备好后，就可以把现有记录导入 Algolia：

php artisan scout:import "AppStudent"

如果网络环境正常，这条命令会把数据库中的 Student 记录分批推送到远程索引。但在实际使用中，很多人会先遇到一个报错：

  [AlgoliaSearchAlgoliaConnectionException]                                          
  Hosts unreachable: Resolving timed out after 1000 milliseconds,Resolving timed out  
   after 1000 milliseconds,Resolving timed out after 3000 milliseconds,Resolving tim  
  ed out after 3000 milliseconds  

这个问题的根源通常不是代码写错，而是默认连接超时时间太短。原文场景里，algoliasearch-client 的默认连接超时只有 1 秒，在网络不稳定或者访问较慢时，很容易在导入阶段直接失败。

通过自定义 EngineManager 延长连接时间

可以创建 app/Services/Scout/EngineManager.php，覆盖默认的 Algolia 驱动创建方式：

<?php
namespace AppServicesScout;

use AlgoliaSearchClient as Algolia;
use AlgoliaSearchVersion as AlgoliaUserAgent;
use LaravelScoutEngineManager as BaseEngineManager;
use LaravelScoutEnginesAlgoliaEngine;

/**
 *
 */
class EngineManager extends BaseEngineManager
{
    public function createAlgoliaDriver()
    {
        AlgoliaUserAgent::addSuffixUserAgentSegment('Laravel Scout', '3.0.7');

        $algolia = new Algolia(
            config('scout.algolia.id'), config('scout.algolia.secret')
        );
        // 设置连接超时时间
        $algolia->setConnectTimeout(30, 30, 30);
        return new AlgoliaEngine($algolia);
    }
}

这里最重要的一行是：

$algolia->setConnectTimeout(30, 30, 30);

也就是把连接超时时间显式放宽，减少因为网络波动导致的大批量导入失败。

在 AppServiceProvider 中替换默认 EngineManager

仅仅创建类还不够，还需要让 Laravel 容器实际使用这个自定义实现。打开 app/Providers/AppServiceProvider.php，在 boot() 中加入：

    public function boot()
    {
        // …… 省略之前代码
        $this->app->singleton(LaravelScoutEngineManager::class, function ($app) {
            return new AppServicesScoutEngineManager($app);
        });
    }

完成这一步后，再重新执行导入命令，通常就能看到分批导入进度：

php artisan scout:import "AppStudent"

Imported [AppStudent] models up to ID: 500
Imported [AppStudent] models up to ID: 1000
Imported [AppStudent] models up to ID: 1500
Imported [AppStudent] models up to ID: 2000
Imported [AppStudent] models up to ID: 2500
Imported [AppStudent] models up to ID: 3000
Imported [AppStudent] models up to ID: 3500
Imported [AppStudent] models up to ID: 4000
Imported [AppStudent] models up to ID: 4500
Imported [AppStudent] models up to ID: 5000
Imported [AppStudent] models up to ID: 5500
Imported [AppStudent] models up to ID: 6000
Imported [AppStudent] models up to ID: 6500
Imported [AppStudent] models up to ID: 7000
Imported [AppStudent] models up to ID: 7500
Imported [AppStudent] models up to ID: 8000
Imported [AppStudent] models up to ID: 8500
Imported [AppStudent] models up to ID: 9000
Imported [AppStudent] models up to ID: 9500
Imported [AppStudent] models up to ID: 10000
All [AppStudent] records have been imported.

如果你在 Algolia 后台的 Indices 菜单里看到 students_index，说明索引已经建立成功，数据也已经被推送上去了。

完成搜索接入后，重点要评估实际收益

导入成功后，就可以直接通过 Scout 发起搜索：

$studens = AppStudent::search('成燕')->get();
dd($studens);

到这里，Laravel 与 Algolia 的基础集成就已经跑通了。对于大数据量检索场景，这类外部搜索引擎通常会比直接查数据库更快，尤其在模糊匹配、排序、实时搜索体验上更容易拉开差距。原文也建议可以尝试填充百万级数据自行测试，看看与数据库直接查询相比差异有多大。

不过，这套方案并不一定适合所有项目。虽然 Algolia 在速度上很有吸引力，但如果你的主要用户和服务器都在国内，网络延迟和稳定性会直接影响导入和查询体验。也正因为这个原因，原作者最终并不算特别推荐把它作为默认检索方案，而是更倾向继续评估 Elasticsearch、Sphinx 这类替代方向。

如果你的项目更看重接入速度、托管能力和较少的自建维护成本，Scout + Algolia 依然是一条很省事的路线；但如果你更看重国内访问稳定性、可控性和长期成本，那就有必要把网络因素一起纳入技术选型，而不是只看“毫秒级搜索”这个单点优势。