PHP + Elasticsearch 实战：从零搭建全文搜索引擎，支持中文分词和高亮显示

摘要：你的 MySQL LIKE 查询拖垮了整个系统？是时候上 Elasticsearch 了。本文带你从 ES 安装、IK 中文分词、PHP 客户端集成，到高亮显示、分页、聚合统计，一步步搭建一套真正可用于生产的全文搜索引擎，附完整可运行代码和性能对比数据（查询速度提升 120 倍）。

一、痛点：LIKE 查询有多惨？

先看一段让无数后端泪目的代码：

// 经典的 MySQL 模糊查询 —— 看起来没什么问题
$keyword = '高性能 PHP 开发';
$articles = DB::table('articles')
    ->where('title', 'LIKE', "%{$keyword}%")
    ->orWhere('content', 'LIKE', "%{$keyword}%")
    ->get();

数据量小的时候一切正常，数据量到 100 万+ 之后：

一句话：MySQL LIKE 是拿锤子做手术刀的活，Elasticsearch 才是为搜索而生的工具。

二、Elasticsearch 核心概念快速入门

在上代码之前，用 3 个类比把 ES 概念说清楚：

MySQL          →  Elasticsearch
数据库(Database) →  索引(Index)
表(Table)       →  类型(Type，已废弃，8.x 用 Index)
行(Row)         →  文档(Document)
列(Column)      →  字段(Field)
Schema         →  Mapping
SQL 查询        →  DSL 查询

三个最重要的原理：

1. 倒排索引（Inverted Index）：把「文档→词」的关系反转为「词→文档列表」，搜索时直接命中，O(1) 查找
2. 分词器（Analyzer）：把一段文字拆成词项（Token），中文必须用 IK 分词器
3. 相关性评分（BM25）：词频（TF）× 逆文档频率（IDF），自动排出最相关的结果

三、环境搭建（5分钟跑通）

3.1 Docker Compose 一键启动

# docker-compose.yml
version: '3.8'
services:
  elasticsearch:
    image: elasticsearch:8.13.0
    container_name: es01
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false  # 开发环境关闭安全认证
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - "9200:9200"
    volumes:
      - es_data:/usr/share/elasticsearch/data
    networks:
      - es_net

  kibana:
    image: kibana:8.13.0
    container_name: kibana01
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    ports:
      - "5601:5601"
    networks:
      - es_net
    depends_on:
      - elasticsearch

volumes:
  es_data:

networks:
  es_net:

# 启动服务
docker-compose up -d

# 验证 ES 是否正常
curl http://localhost:9200
# 返回 {"name":"es01","cluster_name":"docker-cluster","version":{"number":"8.13.0",...}}

3.2 安装 IK 中文分词插件

# 进入容器安装 IK 分词器（版本必须与 ES 一致）
docker exec -it es01 bash
./bin/elasticsearch-plugin install \
  https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.13.0/elasticsearch-analysis-ik-8.13.0.zip

# 重启 ES 生效
docker restart es01

IK 分词器两种模式：

• ik_max_word：最细粒度拆分，适合建索引（词更多 = 召回更全）
• ik_smart：最粗粒度拆分，适合搜索（语义更准确）

验证分词效果：

curl -X POST "localhost:9200/_analyze" -H 'Content-Type: application/json' -d'{
  "analyzer": "ik_max_word",
  "text": "PHP高性能全文搜索引擎实战"
}'
# 结果: ["PHP", "高性能", "高", "性能", "全文", "搜索", "引擎", "实战"]

3.3 安装 PHP 客户端

composer require elasticsearch/elasticsearch:^8.0

四、完整代码实现

4.1 创建 ES 连接客户端

<?php
// src/Search/ElasticsearchClient.php

namespace App\Search;

use Elastic\Elasticsearch\ClientBuilder;
use Elastic\Elasticsearch\Client;

class ElasticsearchClient
{
    private static ?Client $instance = null;

    /**
     * 获取 ES 客户端单例
     */
    public static function getInstance(): Client
    {
        if (self::$instance === null) {
            self::$instance = ClientBuilder::create()
                ->setHosts(['localhost:9200'])
                ->setRetries(2)                    // 失败自动重试 2 次
                ->build();
        }

        return self::$instance;
    }
}

4.2 创建文章索引（含中文分词 Mapping）

<?php
// src/Search/ArticleIndexManager.php

namespace App\Search;

class ArticleIndexManager
{
    private const INDEX_NAME = 'articles';

    /**
     * 创建文章索引
     * Mapping 决定了每个字段如何被分析和存储
     */
    public function createIndex(): array
    {
        $client = ElasticsearchClient::getInstance();

        // 先删除已存在的索引（开发环境）
        if ($client->indices()->exists(['index' => self::INDEX_NAME])->asBool()) {
            $client->indices()->delete(['index' => self::INDEX_NAME]);
        }

        $params = [
            'index' => self::INDEX_NAME,
            'body'  => [
                // -------- 索引设置 --------
                'settings' => [
                    'number_of_shards'   => 1,   // 分片数（单机建议1）
                    'number_of_replicas' => 0,   // 副本数（生产环境建议1）
                    'analysis' => [
                        // 自定义分析器：IK + 停用词
                        'analyzer' => [
                            'ik_custom' => [
                                'type'      => 'custom',
                                'tokenizer' => 'ik_max_word',
                                'filter'    => ['lowercase', 'stop_filter'],
                            ],
                        ],
                        'filter' => [
                            'stop_filter' => [
                                'type'      => 'stop',
                                'stopwords' => ['的', '了', '在', '是', '我', '有', '和'],
                            ],
                        ],
                    ],
                ],
                // -------- 字段 Mapping --------
                'mappings' => [
                    'properties' => [
                        'id' => [
                            'type' => 'integer',
                        ],
                        'title' => [
                            'type'            => 'text',
                            'analyzer'        => 'ik_custom',    // 建索引：最细粒度
                            'search_analyzer' => 'ik_smart',     // 搜索：最粗粒度
                            'fields' => [
                                'keyword' => [                   // 精确匹配子字段
                                    'type' => 'keyword',
                                ],
                            ],
                        ],
                        'content' => [
                            'type'            => 'text',
                            'analyzer'        => 'ik_custom',
                            'search_analyzer' => 'ik_smart',
                        ],
                        'author' => [
                            'type' => 'keyword',                 // 精确匹配，不分词
                        ],
                        'category' => [
                            'type' => 'keyword',
                        ],
                        'tags' => [
                            'type' => 'keyword',                 // 数组也用 keyword
                        ],
                        'view_count' => [
                            'type' => 'integer',
                        ],
                        'created_at' => [
                            'type'   => 'date',
                            'format' => 'yyyy-MM-dd HH:mm:ss||yyyy-MM-dd',
                        ],
                    ],
                ],
            ],
        ];

        return $client->indices()->create($params)->asArray();
    }
}

4.3 批量写入文档（高性能 Bulk API）

<?php
// src/Search/ArticleIndexer.php

namespace App\Search;

class ArticleIndexer
{
    private const INDEX_NAME = 'articles';
    private const BULK_SIZE  = 500;  // 每批写入数量

    /**
     * 从 MySQL 同步文章到 ES（支持百万级数据）
     *
     * @param array $articles 文章数组
     */
    public function bulkIndex(array $articles): array
    {
        $client = ElasticsearchClient::getInstance();
        $chunks  = array_chunk($articles, self::BULK_SIZE);
        $result  = ['success' => 0, 'failed' => 0];

        foreach ($chunks as $chunk) {
            $params = ['body' => []];

            foreach ($chunk as $article) {
                // Bulk API 格式：每条文档需要两行
                // 第一行：操作指令（index/create/update/delete）
                $params['body'][] = [
                    'index' => [
                        '_index' => self::INDEX_NAME,
                        '_id'    => $article['id'],  // 用 MySQL 主键作为 ES 文档 ID
                    ],
                ];
                // 第二行：文档内容
                $params['body'][] = [
                    'id'         => $article['id'],
                    'title'      => $article['title'],
                    'content'    => $article['content'],
                    'author'     => $article['author'],
                    'category'   => $article['category'],
                    'tags'       => $article['tags'] ?? [],
                    'view_count' => (int)$article['view_count'],
                    'created_at' => $article['created_at'],
                ];
            }

            $response = $client->bulk($params);

            // 统计写入结果
            if ($response['errors']) {
                foreach ($response['items'] as $item) {
                    if (isset($item['index']['error'])) {
                        $result['failed']++;
                        error_log('ES 写入失败: ' . json_encode($item['index']['error']));
                    } else {
                        $result['success']++;
                    }
                }
            } else {
                $result['success'] += count($chunk);
            }
        }

        return $result;
    }

    /**
     * 单条文章写入/更新
     */
    public function indexOne(array $article): bool
    {
        $client = ElasticsearchClient::getInstance();

        $response = $client->index([
            'index' => self::INDEX_NAME,
            '_id'   => $article['id'],
            'body'  => $article,
        ]);

        return in_array($response['result'], ['created', 'updated']);
    }
}

4.4 核心搜索功能（高亮 + 分页 + 聚合）

<?php
// src/Search/ArticleSearcher.php

namespace App\Search;

class ArticleSearcher
{
    private const INDEX_NAME = 'articles';

    /**
     * 全文搜索：支持高亮、分页、分类过滤
     *
     * @param string $keyword  搜索关键词
     * @param int    $page     当前页码（从1开始）
     * @param int    $perPage  每页数量
     * @param array  $filters  过滤条件，如 ['category' => 'PHP', 'author' => '张三']
     * @return array
     */
    public function search(
        string $keyword,
        int $page = 1,
        int $perPage = 10,
        array $filters = []
    ): array {
        $client = ElasticsearchClient::getInstance();

        // 构建 Bool 查询（最常用的复合查询）
        $boolQuery = [
            'must'   => [],   // 必须匹配（影响评分）
            'filter' => [],   // 过滤条件（不影响评分，性能更好）
        ];

        // ---- must：全文匹配（多字段，标题权重更高）----
        $boolQuery['must'][] = [
            'multi_match' => [
                'query'  => $keyword,
                'fields' => [
                    'title^3',   // title 权重×3，排名更靠前
                    'content',
                ],
                'type'             => 'best_fields',  // 取得分最高的字段
                'fuzziness'        => 'AUTO',         // 模糊匹配（容错一两个字）
                'minimum_should_match' => '60%',      // 60%词命中即可
            ],
        ];

        // ---- filter：精确过滤（不影响评分） ----
        if (!empty($filters['category'])) {
            $boolQuery['filter'][] = [
                'term' => ['category' => $filters['category']],
            ];
        }
        if (!empty($filters['author'])) {
            $boolQuery['filter'][] = [
                'term' => ['author' => $filters['author']],
            ];
        }
        if (!empty($filters['tags'])) {
            $boolQuery['filter'][] = [
                'terms' => ['tags' => (array)$filters['tags']],
            ];
        }
        // 时间范围过滤
        if (!empty($filters['date_from']) || !empty($filters['date_to'])) {
            $range = [];
            if (!empty($filters['date_from'])) {
                $range['gte'] = $filters['date_from'];
            }
            if (!empty($filters['date_to'])) {
                $range['lte'] = $filters['date_to'];
            }
            $boolQuery['filter'][] = ['range' => ['created_at' => $range]];
        }

        $params = [
            'index' => self::INDEX_NAME,
            'body'  => [
                // ---- 分页 ----
                'from' => ($page - 1) * $perPage,
                'size' => $perPage,

                // ---- 查询 ----
                'query' => ['bool' => $boolQuery],

                // ---- 高亮 ----
                'highlight' => [
                    'pre_tags'  => ['<em class="search-highlight">'],  // 高亮前缀
                    'post_tags' => ['</em>'],
                    'fields'    => [
                        'title'   => ['number_of_fragments' => 0],      // 标题不截断
                        'content' => [
                            'number_of_fragments' => 3,   // 最多3段摘要
                            'fragment_size'        => 150, // 每段150字
                        ],
                    ],
                ],

                // ---- 聚合（分类统计） ----
                'aggs' => [
                    'by_category' => [
                        'terms' => [
                            'field' => 'category',
                            'size'  => 10,
                        ],
                    ],
                    'by_author' => [
                        'terms' => [
                            'field' => 'author',
                            'size'  => 5,
                        ],
                    ],
                ],

                // ---- 评分 + 热度联合排序 ----
                'sort' => [
                    '_score',  // 先按相关性
                    ['view_count' => ['order' => 'desc']],  // 相关性相同时按热度
                ],
            ],
        ];

        $response = $client->search($params);
        return $this->formatResult($response->asArray(), $perPage);
    }

    /**
     * 格式化搜索结果
     */
    private function formatResult(array $response, int $perPage): array
    {
        $hits  = $response['hits'];
        $items = [];

        foreach ($hits['hits'] as $hit) {
            $source    = $hit['_source'];
            $highlight = $hit['highlight'] ?? [];

            $items[] = [
                'id'         => $source['id'],
                // 有高亮则用高亮内容，否则用原始标题
                'title'      => $highlight['title'][0] ?? $source['title'],
                // 内容摘要：优先用高亮片段，没有就截取前200字
                'summary'    => !empty($highlight['content'])
                    ? implode(' ... ', $highlight['content'])
                    : mb_substr($source['content'], 0, 200) . '...',
                'author'     => $source['author'],
                'category'   => $source['category'],
                'tags'       => $source['tags'],
                'view_count' => $source['view_count'],
                'created_at' => $source['created_at'],
                '_score'     => $hit['_score'],
            ];
        }

        // 处理聚合结果
        $aggregations = [];
        if (isset($response['aggregations'])) {
            foreach ($response['aggregations'] as $aggName => $aggData) {
                $aggregations[$aggName] = array_map(
                    fn($bucket) => [
                        'key'   => $bucket['key'],
                        'count' => $bucket['doc_count'],
                    ],
                    $aggData['buckets']
                );
            }
        }

        return [
            'total'        => $hits['total']['value'],
            'per_page'     => $perPage,
            'items'        => $items,
            'aggregations' => $aggregations,
            'took_ms'      => $response['took'],  // ES 内部查询耗时（毫秒）
        ];
    }

    /**
     * 搜索建议（自动补全）
     * 用于搜索框的实时提示
     */
    public function suggest(string $prefix, int $size = 5): array
    {
        $client = ElasticsearchClient::getInstance();

        $params = [
            'index' => self::INDEX_NAME,
            'body'  => [
                'query' => [
                    'match_phrase_prefix' => [
                        'title' => [
                            'query'     => $prefix,
                            'max_expansions' => 10,
                        ],
                    ],
                ],
                'size'    => $size,
                '_source' => ['title'],  // 只返回标题字段，减少数据传输
            ],
        ];

        $response = $client->search($params);

        return array_map(
            fn($hit) => $hit['_source']['title'],
            $response['hits']['hits']
        );
    }
}

4.5 Laravel 集成（ServiceProvider + Facade）

<?php
// app/Providers/ElasticsearchServiceProvider.php

namespace App\Providers;

use App\Search\ArticleSearcher;
use App\Search\ArticleIndexer;
use Elastic\Elasticsearch\ClientBuilder;
use Illuminate\Support\ServiceProvider;

class ElasticsearchServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // 绑定 ES 客户端（单例）
        $this->app->singleton('elasticsearch', function () {
            return ClientBuilder::create()
                ->setHosts(config('elasticsearch.hosts', ['localhost:9200']))
                ->build();
        });

        // 绑定搜索服务
        $this->app->singleton(ArticleSearcher::class);
        $this->app->singleton(ArticleIndexer::class);
    }

    public function boot(): void
    {
        $this->publishes([
            __DIR__ . '/../../config/elasticsearch.php' => config_path('elasticsearch.php'),
        ]);
    }
}

<?php
// app/Http/Controllers/SearchController.php

namespace App\Http\Controllers;

use App\Search\ArticleSearcher;
use Illuminate\Http\Request;

class SearchController extends Controller
{
    public function __construct(
        private readonly ArticleSearcher $searcher
    ) {}

    /**
     * 文章搜索接口
     * GET /api/search?keyword=PHP高性能&category=PHP&page=1
     */
    public function search(Request $request)
    {
        $request->validate([
            'keyword' => 'required|string|min:1|max:100',
            'page'    => 'integer|min:1',
            'category' => 'nullable|string',
        ]);

        $startTime = microtime(true);

        $result = $this->searcher->search(
            keyword: $request->get('keyword'),
            page:    $request->get('page', 1),
            perPage: 10,
            filters: $request->only(['category', 'author', 'tags', 'date_from', 'date_to']),
        );

        $result['php_time_ms'] = round((microtime(true) - $startTime) * 1000, 2);

        return response()->json([
            'code'    => 0,
            'message' => 'ok',
            'data'    => $result,
        ]);
    }

    /**
     * 搜索建议接口（自动补全）
     * GET /api/search/suggest?q=PHP
     */
    public function suggest(Request $request)
    {
        $suggestions = $this->searcher->suggest(
            $request->get('q', ''),
            size: 8
        );

        return response()->json(['data' => $suggestions]);
    }
}

五、数据同步策略

生产环境最头疼的不是搜索，而是数据一致性：MySQL 更新了，ES 里的数据怎么同步？

方案一：MySQL Binlog + Canal（推荐）

MySQL Binlog → Canal Server → Canal Client → ES Bulk Write

优点：完全解耦，不改业务代码，延迟 < 1s
实现：Canal 监听 binlog，PHP Worker 消费并写 ES

<?php
// 简化版 Canal 消费者（实际生产用 Canal PHP 客户端）
class CanalConsumer
{
    public function consume(array $event): void
    {
        $indexer = new ArticleIndexer();

        match ($event['type']) {
            'INSERT', 'UPDATE' => $indexer->indexOne($event['data']),
            'DELETE'           => $this->deleteFromEs($event['data']['id']),
        };
    }

    private function deleteFromEs(int $id): void
    {
        ElasticsearchClient::getInstance()->delete([
            'index' => 'articles',
            'id'    => $id,
        ]);
    }
}

方案二：Observer + 队列（Laravel 项目首选）

<?php
// app/Observers/ArticleObserver.php

namespace App\Observers;

use App\Jobs\SyncArticleToEs;
use App\Models\Article;

class ArticleObserver
{
    // 创建/更新时异步同步到 ES
    public function saved(Article $article): void
    {
        dispatch(new SyncArticleToEs($article->id, 'upsert'))
            ->onQueue('elasticsearch');  // 专用队列，避免阻塞主队列
    }

    // 删除时从 ES 移除
    public function deleted(Article $article): void
    {
        dispatch(new SyncArticleToEs($article->id, 'delete'))
            ->onQueue('elasticsearch');
    }
}

// app/Models/Article.php
class Article extends Model
{
    protected static function booted(): void
    {
        static::observe(ArticleObserver::class);
    }
}

六、性能实测数据

测试环境：8核16G，1000万条文章数据，关键词：「PHP高性能开发实战」

结论：ES 比 MySQL LIKE 快 120 倍，QPS 提升 116 倍，且 CPU 使用率更低。

压测命令（Apache Bench）：

ab -n 10000 -c 100 \
  "http://localhost:8000/api/search?keyword=PHP%E9%AB%98%E6%80%A7%E8%83%BD&page=1"

七、生产环境避坑指南

坑一：分词不准导致召回率低

// ❌ 错误：建索引和搜索用同一个分析器
'analyzer' => 'ik_max_word',

// ✅ 正确：建索引用 ik_max_word（细），搜索用 ik_smart（准）
'analyzer'        => 'ik_max_word',   // 索引时
'search_analyzer' => 'ik_smart',      // 搜索时

坑二：深分页性能崩溃

// ❌ 深分页：from=9990, size=10 会扫描 10000 条
// 搜索第 1000 页时几乎和扫全表一样慢

// ✅ 方案一：限制最大页数（业务允许时最简单）
$page = min($page, 100);  // 最多翻到第100页

// ✅ 方案二：Search After（无限翻页的最优解）
$params['body']['search_after'] = [$lastScore, $lastId];
$params['body']['sort']         = ['_score', ['id' => 'asc']];

坑三：大批量导入时分片不均

# 导入前关闭副本和刷新，速度提升 3~5 倍
curl -X PUT "localhost:9200/articles/_settings" -d'{
  "index": {
    "number_of_replicas": 0,
    "refresh_interval": "-1"
  }
}'

# 导入完成后恢复
curl -X PUT "localhost:9200/articles/_settings" -d'{
  "index": {
    "number_of_replicas": 1,
    "refresh_interval": "1s"
  }
}'

坑四：Mapping 不能随意修改

# ❌ 已有字段的 type 无法直接改（会报错）
# ✅ 解决方案：重建索引（Reindex API）

curl -X POST "localhost:9200/_reindex" -d'{
  "source": {"index": "articles_v1"},
  "dest":   {"index": "articles_v2"}
}'

# 用别名切换，零停机
curl -X POST "localhost:9200/_aliases" -d'{
  "actions": [
    {"remove": {"index": "articles_v1", "alias": "articles"}},
    {"add":    {"index": "articles_v2", "alias": "articles"}}
  ]
}'

坑五：内存不足导致 OOM

# docker-compose.yml：生产环境至少给 ES 分配 4G 堆内存
environment:
  - ES_JAVA_OPTS=-Xms4g -Xmx4g  # 堆内存 = 物理内存的 50%，且不超过 32G

八、质量检查清单

发布前必检 6 项：

• 分词验证：对业务关键词调用 _analyze API 确认分词效果
• 高亮测试：搜索结果中 <em> 标签正确包裹关键词
• 分页正确：第1页、最后一页、超出范围页都测试过
• 数据同步：新增/修改/删除文章后，ES 内数据在 2s 内同步
• 性能压测：高并发场景下 P99 < 200ms
• 异常处理：ES 服务挂掉时，降级到 MySQL 查询，不影响业务

九、总结

一句话总结：MySQL 是你的数据家园，Elasticsearch 是你的搜索引擎——让专业的工具做专业的事，PHP 只是连接它们的胶水，而这正是 PHP 最擅长的。

下期预告：PHP + RabbitMQ 死信队列实战：延迟订单自动取消、超时任务重试，一次搞懂消息队列最复杂的场景（实战案例类）