执行MongoDB的$text全文查询时，如果返回错误信息写着errmsg: text index stemmer error，同时错误码为1370，很大程度上意味着索引中的某个字段值让词干分析器罢工了。这个错误不是查询语句写错，而是索引数据本身触发了文本分析环节的异常。接下来从底层机制、定位方法到修复手段逐一拆解。
错误码1370的触发机制
MongoDB的文本索引在创建和查询时都会对字段内容进行分词、去停用词和词干提取。词干提取使用Snowball算法，具体行为由索引的default_language参数决定，默认是english。词干分析器的职责是把running变成run、把studies变成studi，从而让$text查询能够匹配词形变化。问题在于，Snowball算法在设计之初假设输入是符合某种语言规则的纯文本，一旦字段中混入了无法识别的字符序列，分析器就可能抛出异常并返回错误码1370。
常见的触发场景包括：字段包含孤立的组合音标符号，例如一个单独的U+0301重音符；字段内部存在错误的UTF-8字节序列，可能是从其他系统导入数据时产生的乱码；字段是一段没有空格的超长无意义字符串，例如机器生成的token或哈希值；字段虽然声明为文本索引成员，但实际存储了数组、嵌套文档或二进制数据。此外，MongoDB 4.0及更早版本在处理数组字段的文本索引时存在一些已知缺陷，会在特定查询条件下错误调用词干分析器并导致该错误。错误码1370不是必然出现在索引创建阶段，很多情况下索引可以正常构建，但只有在$text查询遍历到特定词干时才触发异常，这给排查增加了难度。
还需要留意排序规则collation的影响。如果文本索引创建时使用了与查询不同的collation，MongoDB可能会在分析阶段拒绝执行词干提取，或者走不同的分析路径。虽然错误码1370本身指向词干分析，但根本原因往往隐藏在数据质量和索引参数两个维度，而不是查询语法。
定位问题文档的实用方法
要修复错误，首先得找出是哪一条文档、哪一个字段触发了词干分析异常。直接对整个集合执行$text查询可能一直报错，无法缩小范围。最直观的思路是采用二分法：把集合按_id区间分批导出到临时集合，每批重新创建文本索引，观察哪一批索引创建或查询时报1370，再继续对半拆分。这种方法虽然慢，但对生产环境安全，不会影响原始集合。
下面给出一段JavaScript诊断脚本，它遍历一个临时候选集合并逐条插入到另一个带文本索引的空集合中，通过try catch捕获哪个文档导致索引构建失败。为了加快速度，可以在每次插入后不立即建索引，而是批量插入50条后重建一次索引，出错后再缩小范围。注意脚本中使用了printjson输出，实际运行前需要替换数据库连接信息。
// 假设源集合为articles，需要检查的字段为content
var source = db.articles.find({}, {_id: 1, content: 1}).sort({_id: 1}).limit(1000);
var target = db.getSiblingDB("test").tmp_diagnosis;
target.drop();
target.createIndex({content: "text"}, {default_language: "english"});
var batch = [];
var batchSize = 20;
var failedIds = [];
source.forEach(function(doc) {
batch.push(doc);
if (batch.length === batchSize) {
try {
target.insertMany(batch);
target.reIndex(); // 注意：生产环境请使用collMod或重新创建索引，reIndex可能锁库
batch = [];
} catch (e) {
// 缩小这一批，逐条插入
batch.forEach(function(singleDoc) {
var tmp = db.getSiblingDB("test").tmp_single;
tmp.drop();
tmp.createIndex({content: "text"}, {default_language: "english"});
try {
tmp.insertOne(singleDoc);
tmp.reIndex();
} catch (innerErr) {
failedIds.push(singleDoc._id);
printjson(singleDoc);
}
});
batch = [];
}
}
});
print("Failed document IDs:");
printjson(failedIds);
这段代码展示了二分定位的基本逻辑，不过在生产环境中直接调用reIndex会严重影响性能，建议改用临时集合并手动创建索引来验证。更轻量的做法是使用Python脚本通过pymongo逐条读取文档，然后在一个独立测试集合上执行索引创建，失败后立即记录该文档的主键。定位到具体文档后，可以查看字段长度、字节内容以及是否存在不可见字符，常用的检查方式是输出字段的UTF-8字节序列或使用isinstance判断字段类型。
修复方案与代码示例
定位到问题数据后，修复手段取决于脏数据的类型。如果字段内容是非法UTF-8字节，最直接的方案是清洗数据，例如在Python中使用字符串的encode和decode配合errors参数替换无效字节。对于混入数字、布尔值或嵌套文档的情况，需要把它们转换为纯字符串或者从文本索引字段中排除。通常建议在写入前做一次类型归一化，把非字符串值转成JSON字符串或直接丢弃。
如果业务对词干分析没有强依赖，可以在创建文本索引时设置default_language为none，这会禁用词干提取和停用词过滤，只做简单的分词匹配。虽然查询召回率会下降，但能有效规避1370错误。下面的Shell命令展示了如何重建索引并指定default_language为none。
// 删除现有文本索引
db.articles.dropIndex("content_text");
// 重新创建，禁用词干分析
db.articles.createIndex(
{content: "text"},
{default_language: "none", name: "content_text_none"}
);
如果集合中存在多语言内容，应该为每个文本索引显式指定正确的default_language，而不是依赖默认的english。例如西班牙语文本适合使用spanish词干分析器，中文文本则没有Snowball词干分析器，建议使用none。对于版本较低的MongoDB，升级到4.2或更高版本可以修复多项与文本索引词干分析相关的历史bug。完成数据清洗或参数调整后，务必重新创建文本索引，因为旧的索引文件可能已经损坏或者包含错误的分析结果。重建索引可以使用dropIndex加createIndex，也可以使用db.collection.reIndex()，但后者会阻塞整个数据库，只适合小规模数据。
预防措施与索引设计建议
文本索引最适合的输入是用户生成的自然语言文本，比如文章正文、评论内容、产品描述。如果字段包含机器生成的日志、URL、哈希值或JSON序列化结果，应当避免将其纳入文本索引。对于必须参与文本搜索的日志字段，可以在写入前进行清洗，过滤掉控制字符、异常Unicode和超长无空格字符串。MongoDB的$text索引支持部分索引表达式，可以利用partialFilterExpression排除不合规的文档，降低索引构建时出错的概率。
从数据摄入环节增加校验是更彻底的做法。例如在应用层使用UTF-8严格解码确保字节合法性，限制字段最大长度，对于纯数字或布尔类型直接转为字符串。如果集合需要支持多语言检索，建议为不同语言分别创建文本索引，或者使用非词干分析模式。监控方面，可以在MongoDB日志中订阅1370错误，一旦出现就立即检查最近写入的数据，避免脏数据在索引中累积。定期执行db.collection.find({$text: {$search: "test"}})做健康检查并非最佳方案，因为这种查询本身可能触发错误；更安全的做法是备份集合后重建索引，观察是否报错。
最后，错误码1370的核心在于词干分析器遇到了不符合预期的输入。数据治理比反复修复索引更重要。如果业务团队在文本检索上持续遇到该问题，可以考虑迁移到Elasticsearch或OpenSearch等专用搜索引擎，它们对非结构化文本的容错能力更强。但即便使用MongoDB，只要建立良好的数据校验和索引参数管理规范，文本索引仍然可以稳定运行。
MongoDB故障码1370文本索引词干分析错误修改时间：2026-09-25 19:55:48