PHP WindSearch 实现站内搜索：快速集成与配置指南

陈默

发布时间：2026-10-13 | 4人浏览过

原创

WindSearch 是一款轻量级的 PHP 全文检索组件，通过 N-gram 分词技术实现高效搜索。本文将指导开发者如何通过 Composer 安装该库，并利用其提供的 Fast（即用）和 Standard（专业）两种模式完成数据导入、索引构建及搜索查询，从而在 PHP 项目中快速落地站内搜索功能。

安装与环境准备

WindSearch 完全由 PHP 编写，不包含复杂的安装配置，也不占用额外服务器内存。推荐使用 Composer 进行依赖管理，或直接从 GitHub 克隆源码。

第1步：获取代码包

在项目根目录下执行以下命令之一：

# 使用 Composer 安装
composer require rock365/windsearch

# 或使用 Git 克隆仓库
git clone git@github.com:rock365/windsearch.git

安装完成后，确保引入自动加载文件：require_once 'vendor/autoload.php';

即用模式（Fast Mode）配置

即用模式适合对搜索结果精度要求不高但追求极速上线的场景。它无需复杂配置，直接对字符串进行分词并返回主键集合。注意：一个索引库建议固定使用一种模式。

第1步：初始化与导入数据

创建 Wind 实例，清空旧数据后遍历数据库记录进行批次导入：

$Wind = new \WindSearch\Index\Wind('test'); // 'test'为索引名
$Wind->deleteFastIndex(); // 清空之前的即用模式数据

// 假设 $res 是从数据库查询到的数组结果
foreach ($res as $v) {
    $text = $v['title'];       // 需要搜索的文本内容
    $primarykey = $v['id'];    // 对应的主键值
    $Wind->fastIndexer($text, $primarykey);
}

$Wind->fastBatchWrite(); // 批量写入保存
$Wind->fastBuildIndex(); // 构建最终索引

第2步：执行搜索

通过 fastSearch 方法进行搜索，返回的是主键 ID 集合，需结合 MySQL 等数据库查询原始详情：

$Wind = new \WindSearch\Index\Wind('test');
// $page: 页码, $listRows: 每页条数
$res = $Wind->fastSearch($text, $page, $listRows);

// $res 包含主键集合，用于后续从数据库提取完整数据

专业模式（Standard Mode）配置

专业模式支持字段类型映射、多字段搜索及更精细的分词控制，适合复杂的数据检索需求。

第1步：定义映射并创建索引库

参考类似数据库表结构，定义字段的类型（如 text, keyword, primarykey）和分析器：

$mapping = [
    'name' => 'test', // 索引名称
    'field' => [
        [
            'name' => 'id',
            'type' => 'primarykey',
            'primarykey_type' => 'Int_Incremental'
        ],
        [
            'name' => 'title',
            'index' => true,
            'type' => 'text',
            'analyzer' => 'segment'
        ],
        [
            'name' => 'tags',
            'index' => true,
            'type' => 'keyword'
        ],
        [
            'name' => 'score',
            'type' => 'numeric'
        ],
        [
            'name' => 'time',
            'type' => 'date'
        ],
        [
            'name' => 'descr',
            'type' => 'text'
        ]
    ]
];

$Wind = new \WindSearch\Index\Wind('test');
if ($Wind->checkIndex()) {
    $Wind->delIndex(); // 若已存在则先删除
}
$Wind->createIndex($mapping); // 创建新索引

第2步：导入数据并建立索引

对于万级以下数据可一次性导入；大批量数据建议分批处理以提高性能：

$Wind = new \WindSearch\Index\Wind('test');
$Wind->buildIndexInit();
$Wind->loadAnalyzer(true); // 开启分词加速导入

// 遍历结果集导入
foreach ($result as $v) {
    $Wind->indexer($v);
}

$Wind->batchWrite();     // 写入磁盘
$Wind->buildIndex();     // 构建索引（数据量大时耗时较长）

第3步：构造搜索请求

专业模式支持结构化查询语法，可指定具体字段：

$Wind = new \WindSearch\Index\Wind('test');
$Wind->loadAnalyzer();

$query = [
    'match' => [
        'field' => [
            'name' => 'title',
            'query' => $text
        ],
        'list_rows' => $listRows,
        'page' => $page
    ]
];

$res = $Wind->search($query, $page, $listRows);
$resultArr = $res['result']['_source']; // 可直接渲染的前台数据