应优先使用 yiisoft/yii2-sphinx 扩展而非手写 SphinxClient，因其封装连接管理、查询构建与异常处理；需确保 Sphinx 开启 MySQL 协议、Yii 配置 DSN 正确、模型继承 yii\sphinx\ActiveRecord 并声明 indexName；标红须用 yii\sphinx\Snippet 而非 str_replace；Sphinx 的 ngram_len 与 charset_table 必须匹配数据编码。
Yii 框架实现全文搜索，**不推荐手写 SphinxClient 调用原始 API**，而应优先使用官方维护的 yiisoft/yii2-sphinx 扩展——它封装了连接管理、查询构建、结果映射和异常处理，避免手动拼 SQL、解析 matches、重复建连等典型翻车点。
为什么不用 sphinxapi.php 直接 new SphinxClient
手引 sphinxapi.php 是 Yii 1 时代遗留做法，到 Yii 2 后存在几个硬伤：
-
SphinxClient不支持连接池，每次请求都新建 TCP 连接，高并发下易触发Connection refused或超时 - 返回的
$result['matches']是 ID→权重数组，需手动implode+IN查询数据库，极易被 SQL 注入（尤其没过滤$_POST关键词时） - 无法复用 Yii 的 ActiveRecord 关系、缓存、事务机制，比如想查“带作者信息的商品”，就得额外 join，逻辑散落
- 标红必须依赖
BuildExcerpts，但该方法要求传入原始文档内容数组，而你往往只查了 ID，还得再查一遍 DB，白白多一次 IO
yiisoft/yii2-sphinx 的正确接入姿势
不是“装上就能搜”，关键在三步对齐：Sphinx 配置、Yii 组件注册、模型层适配。
- 确保 Sphinx
searchd开启 MySQL 协议：listen = 127.0.0.1:9306:mysql41（不是默认的 9312），否则yii\sphinx\Connection会报SQLSTATE[HY000] [2002] Connection refused - Yii 配置中
dsn必须用 MySQL 形式：mysql:host=127.0.0.1;port=9306，用户名密码留空（Sphinx 默认无认证） - 模型类继承
yii\sphinx\ActiveRecord，并显式声明indexName()，例如：public static function indexName() { return 'product_index'; }，否则查询时找不到索引
关键词标红别在 PHP 层 str_replace
用 str_replace($keyword, '<font color="red">'.$keyword.'</font>', $title) 看似简单，实则埋雷：
- 匹配不区分词界，
“苹果”会把“苹果手机”里的“苹果”也标红，甚至误标 HTML 标签中的文字 - 大小写敏感，用户搜
“PHP”，但数据库存的是“php”，就标不中 - 没做 XSS 过滤，若
$keyword含<script>，直接执行
正确做法是交给 Sphinx 做：用 yii\sphinx\Snippet 类，它调用的是 BuildExcerpts，但已封装好字符集、边界控制和 HTML 转义。示例：
$snippet = new \yii\sphinx\Snippet(['before_match' => '<em>', 'after_match' => '</em>']);<br>$highlights = $snippet->highlight($docs, 'product_index', $keyword);
最常被忽略的一点：Sphinx 的 ngram_len = 1 和 charset_table 必须与你的数据编码严格一致，UTF-8 数据却配 GBK 表，中文永远搜不到——这不是 Yii 的问题，但排查时总先怀疑代码。
