MongoDB 4.0.10执行文本匹配查询报FieldPath字段不可以$开头错误的排查与修复

FieldPath field names may not start with '$' 报错的核心触发逻辑是：MongoDB服务端在解析收到的聚合命令时，把本该作为聚合操作符的键名，错当成了普通文档的字段路径做格式校验。结合你当前的环境（本地MongoDB 4.0.10服务端、课程配套后端代码、包含文本搜索的聚合管道），具体诱因有两个：

• 版本适配错位：课程配套代码依赖的mongodb Node驱动版本过高，和4.0.10的低版本服务端存在命令序列化格式不兼容。高版本驱动生成的聚合命令结构，会让4.0版本的服务端解析错位，把管道数组项的根键（也就是$match、$sort这类合法的聚合操作符）识别为以$开头的非法字段路径，直接触发校验报错。
• 前置依赖缺失：代码中使用的$text文本匹配操作，要求目标集合提前创建对应字段的文本索引，未创建索引时部分版本的服务端会提前触发字段路径校验，跳过正常的操作符识别流程，间接触发同款报错。
  注：堆栈里的UnhandledPromiseRejectionWarning是次生问题，是当前搜索方法没有完整的错误捕获链路，导致抛出的Promise rejection没有被业务代码处理时弹出的Node.js运行时警告，不是报错的核心原因。

按优先级依次执行即可：

• 对齐驱动版本与服务端兼容关系

1. 进入后端项目目录，执行npm ls mongodb查看当前安装的Node驱动版本
2. 如果驱动版本高于3.6.x系列，直接降级到和MongoDB 4.0完全兼容的3.6系列最高版本：执行npm install mongodb@3.6.20
3. 降级后重启后端服务，可先解决大部分由协议错位导致的字段路径识别错误

• 补全文本搜索必需的索引配置
  在Post模型初始化逻辑中，对用于文本搜索的字段创建一次性文本索引：

// 仅在模型挂载时执行一次
Post.collection.createIndex({
  title: "text",
  content: "text"
})

索引创建完成后，原有$text匹配、$meta取文本得分排序的代码不需要修改，4.0版本的MongoDB完全兼容这套语法

• 补全Promise错误捕获逻辑，消除未处理警告

1. 把搜索方法中空的reject()调用修改为传递具体错误对象：reject(new Error("搜索参数必须为字符串类型"))
2. 所有调用Post.search()的接口路由处，补上Promise的.catch()捕获逻辑，将错误信息返回给前端，避免未捕获的Promise rejection触发运行时警告

内容的提问来源于stack exchange，提问作者BobRoyAce