$meta: "textscore" 必须与 $text 查询绑定使用，否则报错或返回 null；atlas 上需改用 $search 和 $meta: "searchscore"，且必须在对应查询阶段后引用。
$meta: "textScore" 必须和 $text 查询绑定使用，否则直接报错或返回 null；在 Atlas 上还必须用 MongoDB Search 替代原生 $text。
为什么 $meta: "textScore" 在聚合中总返回 null 或报错
根本原因是它不是独立可用的元数据字段，而是 $text 查询执行后附带的“副产品”。MongoDB 要求：只要你在管道里用了 {$meta: "textScore"}，前面就必须有含 $text 的 $match 阶段。
- 错误写法：
db.coll.aggregate([{$project: {score: {$meta: "textScore"}}}])→ 报错："textScore" requires a $text query - 正确顺序：必须是
{$match: {$text: {$search: "xxx"}}}→ 后续阶段才能引用{$meta: "textScore"} - 注意：Stable API V1 禁用
textScore，若启用了 Stable API，这个写法会静默失败（不报错但值为 null）
在 $sort 阶段按文本得分降序排列的写法
排序本身很简单，但容易忽略两点：一是必须保证 $meta 出现在 $sort 之前（比如在 $project 里提前提取），二是不能直接在 $sort 里嵌套 $meta 表达式（语法不支持）。
- ✅ 推荐写法：先
$project提取分数，再$sortdb.coll.aggregate([ { $match: { $text: { $search: "mongodb tutorial" } } }, { $project: { title: 1, content: 1, score: { $meta: "textScore" } } }, { $sort: { score: -1 } } ]) - ❌ 错误写法：
{$sort: {"$meta": "textScore"}}→ 语法错误，$meta不允许出现在$sort的键路径中 - ⚠️ 注意：如果字段名已存在（如文档里本来就有
score字段），$project中的score: {$meta: "textScore"}会覆盖原始值
Atlas 用户别用 $text —— 改用 $search + searchScore
如果你用的是 MongoDB Atlas（尤其是启用了 MongoDB Search 的集群），原生 $text 已被弃用。此时 $meta: "textScore" 不起作用，必须切换到 $search 管道阶段，并用 $meta: "searchScore"。
- ✅ Atlas 正确写法：
db.coll.aggregate([ { $search: { text: { path: "title", query: "mongodb tutorial" } } }, { $project: { title: 1, score: { $meta: "searchScore" } } }, { $sort: { score: -1 } } ]) - ⚠️ 关键限制：
$meta: "searchScore"只能在$search阶段之后使用，且不能和$text混用；否则 MongoDB 会记录警告日志，但不中断执行 - ? 提示：Atlas 上
$search支持更多能力（如高亮、嵌入式字段、多语言分析），searchScore也比旧版textScore更稳定、可解释性更强
常见陷阱：投影中字段名冲突与空分值处理
即使语法全对，实际结果仍可能出人意料——尤其是当部分文档匹配但未命中关键词时，$meta: "textScore" 可能为 null，导致 $sort 把它们排在最前（因为 null 在 MongoDB 排序中比数字小）。
- 规避方法：用
$ifNull统一兜底{ $project: { title: 1, score: { $ifNull: [{ $meta: "textScore" }, 0] } } } - 字段覆盖风险：若原始文档含
textScore字段，又在$project里写textScore: {$meta: "textScore"}，该字段会被元数据覆盖——这不是 bug，是设计行为 - 调试建议：加一个
$addFields: { debug: { $meta: "indexKey" } }可快速确认当前走的是哪个索引（仅限自托管环境，Atlas 不支持indexKey）
真正难的不是写出能跑的语句，而是意识到 $meta 从来不是“取一个值”，而是在特定查询上下文中“解锁一个隐式输出”。漏掉那个上下文（$text 或 $search），整条管道就失去语义基础。
