ngram是MySQL≥5.7.6唯一开箱即用的中文全文检索方案，需同时满足版本≥5.7.6、启用ngram插件、建索引时显式指定WITH PARSER ngram、查询MATCH字段顺序与索引完全一致四重条件。
ngram 是 MySQL 唯一开箱即用、无需额外安装的中文全文检索方案，但必须满足版本（≥5.7.6）、表结构、索引定义和查询写法四重条件，缺一不可。
确认 MySQL 版本与 ngram 插件状态
ngram 是内置插件，不需手动安装，但前提是 MySQL ≥ 5.7.6。低于该版本或使用 MariaDB 将无法启用。
- 执行
SELECT VERSION();确认版本；若返回如8.0.33或5.7.31，则支持 - 检查插件是否已加载：
SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME = 'ngram';，结果应为ACTIVE - 若未激活，需在配置文件（
my.cnf）中添加ngram_token_size = 2并重启 mysqld —— 注意：仅配置此项即可触发插件加载，无需INSTALL PLUGIN
创建或修改全文索引时必须显式指定 WITH PARSER ngram
默认 FULLTEXT 索引对中文无效，因为 MySQL 原生分词器依赖空格，而中文无词界分隔符。ngram 必须通过 WITH PARSER ngram 显式绑定，且位置严格固定在语句末尾。
- 新建表时：
CREATE TABLE articles (id INT, title VARCHAR(255), content TEXT, FULLTEXT(title, content) WITH PARSER ngram) ENGINE=InnoDB; - 已有表添加索引：
ALTER TABLE articles ADD FULLTEXT INDEX ft_title_content (title, content) WITH PARSER ngram;——WITH PARSER ngram不能省略，不能写成USING ngram或PARSER=ngram - 列类型必须是
CHAR/VARCHAR/TEXT，字符集推荐utf8mb4；content(200)这类前缀长度写法会直接报错 1064
MATCH() AGAINST() 查询必须严格匹配索引字段顺序
ngram 全文索引不支持布尔模式（IN BOOLEAN MODE），也不支持查询扩展（WITH QUERY EXPANSION），只允许自然语言模式（可省略）。更重要的是，MATCH() 中字段顺序必须与索引定义完全一致，否则报错。
- 如果索引是
FULLTEXT(title, content) WITH PARSER ngram，则查询只能写MATCH(title, content) AGAINST('数据库') -
MATCH(content, title) AGAINST('数据库')会直接触发错误ERROR 1064 - 关键词长度不能低于
ngram_token_size（默认为 2）：搜索单字如'数'会返回空结果；若需支持单字，需将配置设为ngram_token_size = 1，但会显著增加索引体积和查询噪音 - 搜索字符串必须是常量，不能是列名或表达式，例如
AGAINST(t.keyword)不合法
ngram_token_size 设置影响分词粒度与召回率
ngram 按固定字符长度切分文本，不是语义分词。设置过小（如 1）会导致大量无意义组合（如“的”、“了”、“人”），增大索引并稀释权重；过大（如 4）则可能漏掉常见双音节词（如“数据”“系统”）。
- 默认值
ngram_token_size = 2覆盖大多数中文双音节词，推荐从该值起步 - “数据库”会被拆为
'数据'和'库'（注意：不是“数据”+“库”，而是“数据”+“据库”，因是滑动窗口）—— 实际切分逻辑是连续 n 字符序列，所以 “数据库”（3 字）→'数据','据库' - 调整后必须重建全文索引才生效：
ALTER TABLE articles DROP INDEX ft_title_content, ADD FULLTEXT INDEX ft_title_content (title, content) WITH PARSER ngram; - 重建索引前，建议先清空大表数据再导入，比在已有 FULLTEXT 索引上批量 INSERT 快数倍
真正卡住人的往往不是配置，而是字段顺序错位、token_size 与实际关键词长度不匹配、或误用了布尔模式——这些错误不会提示“不支持中文”，而是静默返回空结果或语法报错，容易让人绕远路排查。
