企业官网建设流程全解析

Mongoose 与 Lodash 兼容性指南：cloneDeep 的正确替代方案与底层原理

【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose

Mongoose 的大部分 API 与 Lodash 的工具函数可以和平共处，但有一个众所周知的坑：绝不应对任何 Mongoose 对象调用 Lodash 的cloneDeep()。本文基于 Mongoose 官方文档 docs/lodash.md 展开，深入剖析cloneDeep()抛错this.__parentArray.$path is not a function的底层原因（Mongoose 数组的 Proxy 实现与内部__parentArray引用链），并给出toObject() + init()、$clone()等经过验证的深拷贝替代方案，帮助你安全地在 Mongoose 项目中混用 Lodash。

一、总体兼容性：大部分情况下 Mongoose 与 Lodash 相处融洽

Mongoose 官方文档的结论非常明确："For the most part, Mongoose works well with Lodash"（大多数情况下，Mongoose 与 Lodash 配合良好）。你可以在项目中放心使用 Lodash 的绝大多数纯工具函数，例如：

• _.isEqual()/_.isEqualWith()做深度相等比较——Mongoose 自身的测试套件就在使用 lodash 的相等比较函数，见 test/model.findOneAndUpdate.test.js 与 test/model.findOneAndUpdate.test.js；
• _.pick()、_.omit()、_.get()、_.set()、_.map()、_.filter()等不修改对象原型的纯函数，作用于普通 POJO 数据或文档的toObject()结果时没有副作用。

需要警惕的只有少数会对对象做整体遍历或深拷贝的函数，其中最典型、最容易踩坑的就是cloneDeep()。

二、核心陷阱：不要对 Mongoose 对象使用 lodash 的cloneDeep()

官方文档明确划出了红线：Lodash 的cloneDeep()不能用于任何 Mongoose 对象，包括：

• 连接（connections）
• 模型类（model classes）
• 查询（queries）
• 尤其是 文档（documents）

一个看起来人畜无害、却会翻车的典型写法如下：

const _ = require('lodash'); const doc = await MyModel.findOne(); // ❌ 错误的做法：对 Mongoose 文档做深拷贝 const newDoc = _.cloneDeep(doc); newDoc.myProperty = 'test'; await newDoc.save();

只要MyModel的 schema 中存在任何数组属性（例如tags: [String]、嵌套子文档数组等），上述代码在newDoc.save()阶段就会抛出如下错误：

TypeError: this.__parentArray.$path is not a function

三、为什么会报错：Proxy 数组与内部引用链断裂

3.1 Mongoose 6 起数组是 Proxy

官方文档给出的直接原因是：Lodash 的cloneDeep()不会正确处理 Proxy 对象，而自 Mongoose 6 起，Mongoose 的数组（MongooseArray）是基于 JavaScriptProxy实现的。

cloneDeep()在递归遍历时，会逐层复制对象的属性值，但 Proxy 的拦截逻辑（尤其是对数组索引、length、push/pull等操作的拦截）并不会被忠实保留。深拷贝产出的"新数组"只是一堆失去 Mongoose 内部元数据的普通 JS 数组，它再也无法参与 Mongoose 的变更追踪（change tracking）与save()流程。

3.2 崩溃点在__parentArray.$path调用链

错误信息this.__parentArray.$path is not a function可以在源码中找到确切的对应实现。在 lib/types/arraySubdocument.js 中，数组子文档通过this.__parentArray = parentArr持有对父数组的引用：

this.__parentArray = parentArr;

而当子文档需要计算自己的完整路径（例如parent.tags.0）时，会调用父数组的$path()方法，见 lib/types/arraySubdocument.js：

if (this.__index == null || !this.__parentArray?.$path) { return path == null ? this.__parentArray.$path() : this.__parentArray.$path() + '.' + path; }

类似的__parentArray引用还被用于数组元素移除（lib/types/arraySubdocument.js 中的this.__parentArray.pull({ _id: _id })）、$session()透传（lib/schema/documentArray.js）以及保存子文档等关键操作。

cloneDeep()复制的对象中，子文档虽然表面上还在，但它内部指向的__parentArray已被替换为普通数组/普通对象，不再具备$path方法，于是当save()内部遍历数组子文档、调用路径计算时，就触发了上述 TypeError。

3.3 展开运算符同样危险

类似的内部引用问题不只存在于cloneDeep()。在 lib/helpers/document/handleSpreadDoc.js 的源码注释中明确写道：对 Mongoose 文档使用**展开运算符（spread operator）**得到的 POJO "有引发无限递归的趋势"，因此 Mongoose 在set()内部专门对这类对象做了拦截，并且keysToSkip中明确跳过了'__index'、'__parentArray'、'_doc'这些内部字段：

const keysToSkip = new Set(['__index', '__parentArray', '_doc']);

这说明：凡是破坏文档内部引用链（__parentArray、_doc、$__等）的操作，都可能让 Mongoose 的变更追踪机制失效或崩溃，cloneDeep()只是其中最容易踩中的一种。

四、正确做法一：toObject()+new Model().init()

官方文档给出的推荐替代方案是：先把文档转成普通 POJO，再用新的模型实例初始化，而不是直接深拷贝 Mongoose 文档本身：

const doc = await MyModel.findOne(); // ✅ 正确的做法：toObject() 转 POJO，再用新实例 init() const newDoc = new MyModel().init(doc.toObject()); newDoc.myProperty = 'test'; await newDoc.save();

这样做的原理：

1. doc.toObject()把 Mongoose 文档（含 Proxy 数组、__parentArray等内部引用）转换为干净的普通 JavaScript 对象，彻底绕开 Proxy 深拷贝问题；
2. new MyModel()创建全新的模型实例；
3. init()是 Mongoose 文档的公开 API，用于用 MongoDB 返回的原始文档（或任意 POJO）填充一个新文档。它底层调用$__init()，会重新建立正确的内部结构（数组会被重新包装为 MongooseArray、子文档重新挂上__parentArray引用等），见 lib/document.js 的实现。

需要注意init()会触发init中间件（lib/document.js），且init钩子是同步执行的。另外toObject()默认不会保留不可枚举路径与虚拟属性，如果 schema 中定义了虚拟属性（virtuals）且希望复制到新文档中，应显式传入doc.toObject({ virtuals: true })。

五、正确做法二：Mongoose 内置的$clone()

如果你需要的正是"文档的深拷贝"且希望保留文档身份与变更追踪状态，官方还提供了文档级别的$clone()方法，见 lib/document.js：

const doc = await MyModel.findOne(); // ✅ 官方提供的文档深拷贝 API const clonedDoc = doc.$clone(); clonedDoc.myProperty = 'test'; await clonedDoc.save();

从源码看，$clone()做的事情远比 Lodash 深拷贝更精确：

• 以this.constructor为模板创建同模型的新实例；
• 通过clone(this._doc, { retainDocuments: true, parentDoc: clonedDoc })深拷贝内部数据，并且在 lib/helpers/clone.js 中可以看到：当retainDocuments为 true 时，会调用子文档的$clone()，并显式保留__index与__parentArray（clonedDoc.__parentArray = options.parentArray ?? obj.__parentArray），同时用$__setParent()重新建立父文档关系；
• 拷贝$__变更追踪缓存（activePaths、版本信息等），让克隆出的文档具备独立且完整的脏路径跟踪能力。

因此，如果你要的是"复制一个可独立保存的 Mongoose 文档"，$clone()是比cloneDeep()更语义化、更安全的官方方案。与之相对，Mongoose 内部通用的clone()工具（lib/helpers/clone.js）虽然也支持对 Mongoose 原生类型（ObjectId、Decimal128、UUID、Buffer、Date 等）的正确克隆，但它是内部 API（@api private），日常业务代码中应优先使用toObject()或$clone()。

六、几个实用的决策建议

在实际开发中，可以按需求选择正确的"拷贝"姿势：

核心原则一句话：Mongoose 对象（尤其是文档）是"活的"，它们带有内部引用链与变更追踪机制，不要用通用深拷贝库去复制它们；先toObject()转成普通数据，或者使用 Mongoose 官方提供的init()/$clone()。

七、小结

• Mongoose 与 Lodash 绝大多数场景下可以混用，真正的雷区集中在cloneDeep()这类对对象进行整体递归深拷贝的函数上；
• 报错this.__parentArray.$path is not a function的根源是 Mongoose 6 的 Proxy 数组在深拷贝后丢失了内部__parentArray引用链（对应实现见 lib/types/arraySubdocument.js）；
• 官方推荐的替代方案new MyModel().init(doc.toObject())简单可靠；需要保留文档状态时，可使用官方$clone()（lib/document.js）；
• 涉及文档拷贝的代码，务必先想清楚"我要的是普通数据还是可保存的 Mongoose 文档"，再选择对应的转换方式。

【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose