MongoDB Node.js 的 findOneAndUpdate 更新成功却返回旧文档

MongoDB 里的状态字段已经更新，Node.js 的 findOneAndUpdate() 返回值却仍是旧状态。继续重试更新，有时还会让 $push 的历史记录重复增加。这种现象需要先区分“写入没有发生”和“返回了更新前的文档”。

原生 mongodb 驱动的 findOneAndUpdate() 默认返回更新前的文档。要取这次更新后的内容，使用 returnDocument: 'after'。不要把 mongosh、Mongoose 或旧驱动的同名方法选项直接搬过来。

先确认使用的是哪一套 API

查看应用的 import 和实际安装的依赖版本。以下示例针对原生 Node.js 驱动 6.x 的接口，当前驱动也支持这组选项；它不是 Mongoose Model 的调用示例。

returnNewDocument: true 不是这里采用的原生驱动选项。不要给当前调用同时堆上 new、returnOriginal 和 returnDocument。应按实际依赖选择一个有效接口，避免不知道究竟是哪项生效。

如果数据库查询确认目标记录已更新，而函数返回的字段正好是更新前值，优先检查返回选项。若记录根本没变，则继续核对数据库、集合、过滤条件、字段类型及写入错误；调整返回选项不会修复错误的 _id 或失败的写入。

在第三个参数里要求返回更新后文档

下面的函数接收已经取得的集合对象及真实 _id。仅在隔离测试集合中选择自己准备的记录验证，不要给生产任务重复调用更新来观察返回值。

async function changeStatus(collection, recordId, nextStatus) {
  const updated = await collection.findOneAndUpdate(
    { _id: recordId },
    { $set: { status: nextStatus } },
    {
      returnDocument: 'after',
      includeResultMetadata: false,
      upsert: false
    }
  );

  if (updated === null) {
    throw new Error('No matching document');
  }
  return updated;
}

recordId 必须与数据库字段类型一致。字符串与 BSON ObjectId 不是同一类型；不要为了让示例运行就放宽过滤条件或改成更新任意一条记录。nextStatus 也应先通过应用自己的业务校验。

returnDocument 放在第三个选项对象里，不是写进 $set。这里显式关闭 upsert，因此未匹配时返回 null，不会新建一条业务记录。捕获异常时保留原错误信息，不要把所有异常都解释成“未找到”。

文档版本和返回包装是两项设置

returnDocument: 'after' 决定返回更新前还是更新后的内容；includeResultMetadata 决定外面是否有结果包装，两者不能互相替代。

Node.js 驱动从 6.0 起默认直接返回文档或 null。显式设置 includeResultMetadata: false 后，应直接读取 updated.status，不要继续按旧代码读取 updated.value.status。该选项从 5.7 起提供，但升级跨大版本还需检查项目其他兼容性，不能仅凭这一项就直接替换依赖。

确实需要 lastErrorObject 等元数据时，可选择 includeResultMetadata: true，并按结果对象的 value 读取文档。不要同时保留两种未经区分的读取方式，也不要把业务文档自己名为 value 的字段当成驱动包装。

验证一次更新，避免重复副作用

在测试记录上让新旧状态明显不同，核对返回文档、随后读取的数据库字段以及未修改的字段。若原操作还包含 $inc 或 $push，确认它们只执行了一次；返回旧值不等于写入失败，手工重复调用可能造成额外计数或历史项。

单独执行 updateOne() 再 findOne() 虽然也能读取文档，但两次操作之间可能有其他写入，读到的不一定是刚才那次修改对应的状态。需要更新并取得该操作结果时，保留 compound operation 的语义。

改动通常只涉及选项和返回值读取代码。保留原调用版本以便回退；恢复选项不会撤销已经发生的写入，也不会自动删除重试产生的历史记录。此类数据修复须依据业务记录单独核对。