Mongoose CHANGELOG 深度解读从 9.9.5 回溯 9.x 系列的核心变更、破坏性改动与性能演进【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose本指南以当前仓库根目录下的 CHANGELOG.md覆盖 962 个版本条目、从 9.9.5 一直回溯到 8.x/7.x/6.x 各维护分支为骨架系统梳理 Mongoose 9.x 系列引入的新特性、破坏性变更、性能优化与 TypeScript 类型演进并对照 lib 源码与 docs 文档给出落地依据。读完本文你将掌握 Mongoose 9 相比 8.x 的关键差异、9.x 迭代中的新 API 与配置项以及如何结合 CHANGELOG 制定自己的升级与排查策略。一、Mongoose 版本发布节奏与多分支维护策略CHANGELOG 的头部清晰地展示了 Mongoose 的版本管理方式主版本 9.x 与旧主版本 8.x、7.x、6.x 并行发布例如同一时间段内同时出现9.9.5 / 2026-09-048.24.4 / 2026-08-217.8.9 / 2026-02-046.13.8 / 2025-01-20从 docs/version-support.md 可以确认对应的维护策略版本线状态说明Mongoose 9当前版本2025-11-21 发布新功能集中于此Mongoose 8先前版本2023-10-31 发布8.x 持续接收修复至少到 2026-02-01Mongoose 7旧版2023-02-27 发布处于遗留支持状态Mongoose 6有限维护仅安全补丁与请求的 bug 修复2027-02-01 停止一切更新Mongoose 5生命周期结束2024-03-01 EOL这种「一条主线 多条维护分支」的节奏意味着当你升级 Mongoose 时不仅要看 9.x 的新功能还要注意 8.x/7.x 分支上的修复回移backport。例如8.24.4明确标注了(8.x backport)8.23.0则把flattenUUIDs特性回移到了 8.x 线。当前仓库 package.json 中version为9.9.5与 CHANGELOG 头部条目一致。二、Mongoose 9.0.0一次彻底的大版本重构CHANGELOG 中9.0.0 / 2025-11-21条目集中列出了全部BREAKING CHANGE这是从 8.x 升级时必须逐条核对的内容主要可分为四类。1. 中间件与回调模型的变化彻底移除基于回调的 pre 中间件pre()钩子不再接收next()参数。9.0.0 的迁移指南 docs/migrating_to_9.md 给出了对照写法// Mongoose 8.x不再支持 schema.pre(save, function(next) { // 异步操作 next(); }); // Mongoose 9.xasync/await 或 Promise schema.pre(save, async function() { // 异步操作 }); schema.pre(save, function() { return new Promise((resolve) { // 异步操作 resolve(); }); });验证路径异步化SchemaType.prototype.doValidate()改为返回 Promiseasync function doValidate(value, scope, options)不再接受回调validate()也改为 async 函数并直接调用 Kareem 钩子相关代码见 lib/schemaType.js。移除_executionStack以获得更清晰的错误堆栈移除schemaType.caster/casterConstructor属性改用embeddedSchemaType与Constructor。2. 驱动与依赖升级升级到 MongoDB Node.js Driver v79.0.0随后 9.6.0 升级到 driver 7.2、9.8.0 升级到 driver 7.5package.json 中mongodb: ~7.5与之一致。移除bson直接依赖统一通过mongodb/lib/bson使用 BSON9.9.2 的类型层面也从bson改为从mongodb导入。移除浏览器构建改为独立的mongoosejs/browser包。3. 查询语义收紧findOne(null)、find(null)等直接抛错不再静默返回首条文档。更新管道update pipeline默认禁用向updateOne()/updateMany()/findOneAndUpdate()传入管道数组会抛错必须显式开启updatePipeline: true。FilterQuery属性在 TypeScript 中不再退化为anycreate()与insertOne()参数类型更严格。4. 类型系统与命名修正id从 Document 基类属性改为虚拟属性_id相关类型随之调整。RootQuerySelector、Condition等类型与 MongoDB driver 类型合并统一。复数化修正virus - viruses这也提醒你集合名自动复数化可能出现与旧库不一致的情况。三、9.x 系列值得关注的新特性CHANGELOG 中大量feat前缀条目记录了 9.x 的功能演进以下按模块分类。Schema 与验证strictRead选项9.8.0在文档水合hydration阶段过滤或抛错处理不在 schema 中的字段。源码 lib/document.js 中init()会读取docSchema.options.strictRead当路径类型为adhocOrUndefined且strictRead为throw时抛出StrictModeError为true时直接跳过该字段。对应文档说明见 docs/guide.md 中的strictRead小节。allowNull选项9.6.0即使字段非required也可以禁止null值。实现位于 lib/schemaType.jsrequired: true与allowNull: false同时指定会抛出错误错误消息见 lib/error/messages.js。Union Schema 支持8.18.0 起9.x 持续完善toJSONSchema支持 union、union 的验证与子文档实现以及对 union 应用 create 强转时的基本类型转换。flattenUUIDs选项9.2.0toObject()与toJSON()可展开 UUID8.23.0 已回移。toJSONSchema()完善9.7.1 为 ObjectId 输出 regex 模式、9.4.0 支持 unions、9.9.2 修复 enum 重复null与 object 形式 enum。Model 与查询pathsToSave9.1.0save()仅保存指定路径9.8.0 补充了SaveOptions.pathsToSave类型9.2.2 修正其对所有更新操作符的过滤行为。乐观并发增强9.1.0 增加optimisticConcurrency的 exclude 选项9.4.0/9.8.0/9.9.2 修复了嵌套路径、排除父路径、map 通配符等场景下的版本键处理。returnDocument全局选项9.2.0新增全局returnDocument同时弃用returnOriginal与new9.9.3 文档进一步补充。跳过中间件选项9.2.0可在调用时跳过 middleware 执行对应 issue #15883。bulkSave()完善9.8.0 修复插入新文档时的版本键处理9.9.2 确保事务重试时文档会话被设置9.9.4 按文档 id 索引 bulkSave 写错误以提升性能。hydrate()增强9.2.0 支持strict选项8.19.0 支持virtuals选项。聚合与驱动能力pipelineForUnionWith()9.3.08.24.0 回移复用管道与$unionWith组合TypeScript 友好。Node.js TracingChannel 支持9.7.0为 APM 埋点提供能力实现见 lib/tracing.js使用node:diagnostics_channel。Standard Schema 适配9.7.0为 Model 增加标准 schema 适配器类型层改为使用standard-schema/spec9.7.3与 package.json 依赖一致。四、性能优化路线9.x 的持续调优CHANGELOG 中perf前缀条目在 9.x 后期显著增多形成了一条清晰的性能优化主线toObject()/toJSON()9.9.0 用更快的字符串检查、避免在无 getter 路径上调用isSelected9.9.3 缓存投影元数据、对扁平投影避免扫描全部投影路径。save()链路9.1.2 仅选择_id检查文档存在性9.7.1 减少不必要的 Promise 分配与路径/默认值/脏状态开销9.8.1 避免重复构建 modified paths、避免每次实例化文档都清空 required paths 缓存。insertMany()与变更追踪9.9.0 提升insertMany()与通用变更追踪性能。时间戳9.9.0 除非 upsert 被设置否则不为createdAt添加$setOnInsert。杂项9.8.1 缓存array.unique的toString()结果9.9.2 内联$__hasOnlyPrimitiveValues()中的类型检查8.20.3 使用Object.hasOwn替代hasOwnProperty。这些优化大多伴随对应 issue 编号如 #14394、#16373、#16385在排障时可反向追踪具体提交。五、TypeScript 类型系统的持续演进9.x 的类型工作贯穿始终CHANGELOG 中types(...)前缀条目密集推断能力InferRawDocType/InferHydratedDocType的持续修正子文档、文档数组、嵌套 map、union 分发9.3.3 使MergeType对 union 具有分配性。严格化FilterQuery不再回退到anyexactOptionalPropertyTypes编译支持9.6.2查询过滤类型尊重字符串联合与 enum9.6.0对$and中无法识别的操作符报类型错误9.4.0。文档类型细节id虚拟属性默认加入HydratedDocumenttoObject()保留已 populate 路径除非depopulate: trueModel.schema在省略TSchema时仍保持类型。工具链9.2.2 引入 TSTyche 做类型测试对应脚本test:types见 package.json并逐步替换 tsd。六、典型 Bug 修复模式值得记住的「坑」CHANGELOG 的fix条目是对实际使用最有参考价值的部分几个高频主题值得注意sanitizeFilter 防护8.24.3/9.9.2 将sanitizeFilter应用到countDocuments()与cursor()9.1.6 处理其他顶层查询操作符9.5.0 修复__proto__相关更新与$set方法的误判。原型污染防护9.2.2 修复setDefaultsOnInsert的点号路径处理并防止原型污染9.1.4 防止访问原型上的嵌套路径导致崩溃。数组子文档路径重建8.24.1/9.7.2 在数组重排与删除后重新索引 subdoc保证后续嵌套修改保存到正确路径对应 lib/types/documentArray 相关逻辑。地图Map路径9.9.4 修复移除 map 路径时子路径清理、嵌套路径下 map 的移除以及克隆时 map 值 schematype 的单例保持。optimisticConcurrency与排除路径9.8.0 修复乐观并发下被排除父路径的处理9.9.2 支持 map 通配符。七、文档与生态建设9.x 在文档层面也有不少投入CHANGELOG 记录了新增 Atlas Vector Search 与 Atlas Search 文档9.9.4。生成llms.txt9.7.0并有配套脚本 scripts/generateLLMsTXT.js。加入 MongoDB Knowledge 助手侧边栏9.7.1、深色模式9.0.1、代码块复制按钮8.20.1。大量链接修复与文档重写documents docs 重写、populate 选项补充、sample()示例扩展等。八、升级建议与阅读方法结合 CHANGELOG 与迁移文档推荐的升级路径是先读迁移指南若从 8.x 升级到 9.x通读 docs/migrating_to_9.md更早版本需逐级升级7.x → 8.x → 9.x对应 docs/migrating_to_8.md 等文档。逐条核对 BREAKING CHANGE以 9.0.0 条目的破坏性改动为清单重点检查 pre 中间件next()、更新管道、findOne(null)、id虚拟属性等。关注本版本线的新特性9.8.0 的strictRead、9.6.0 的allowNull、9.2.0 的returnDocument都是可能直接改变业务行为的配置项可结合 docs/guide.md 与 lib/schema.js 的默认值确认行为。把 perf/fix 条目当作升级红利9.x 后期的性能优化toObject、save、insertMany在升级后通常无需改代码即可受益。注意跨分支行为差异8.x 与 9.x 并行的修复如 sanitizeFilter、clone 隔离语义可能不完全一致测试要覆盖两个目标版本。最后升级后建议运行仓库自带的测试体系做验证npm testMocha 全量测试、npm run test:typesTSTyche 类型测试配置见 tstyche.json并在升级前用npm ls mongoose mongodb确认依赖树中没有锁死旧驱动的包。【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mongoose CHANGELOG 深度解读：从 9.9.5 回溯 9.x 系列的核心变更、破坏性改动与性能演进
Mongoose CHANGELOG 深度解读从 9.9.5 回溯 9.x 系列的核心变更、破坏性改动与性能演进【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose本指南以当前仓库根目录下的 CHANGELOG.md覆盖 962 个版本条目、从 9.9.5 一直回溯到 8.x/7.x/6.x 各维护分支为骨架系统梳理 Mongoose 9.x 系列引入的新特性、破坏性变更、性能优化与 TypeScript 类型演进并对照 lib 源码与 docs 文档给出落地依据。读完本文你将掌握 Mongoose 9 相比 8.x 的关键差异、9.x 迭代中的新 API 与配置项以及如何结合 CHANGELOG 制定自己的升级与排查策略。一、Mongoose 版本发布节奏与多分支维护策略CHANGELOG 的头部清晰地展示了 Mongoose 的版本管理方式主版本 9.x 与旧主版本 8.x、7.x、6.x 并行发布例如同一时间段内同时出现9.9.5 / 2026-09-048.24.4 / 2026-08-217.8.9 / 2026-02-046.13.8 / 2025-01-20从 docs/version-support.md 可以确认对应的维护策略版本线状态说明Mongoose 9当前版本2025-11-21 发布新功能集中于此Mongoose 8先前版本2023-10-31 发布8.x 持续接收修复至少到 2026-02-01Mongoose 7旧版2023-02-27 发布处于遗留支持状态Mongoose 6有限维护仅安全补丁与请求的 bug 修复2027-02-01 停止一切更新Mongoose 5生命周期结束2024-03-01 EOL这种「一条主线 多条维护分支」的节奏意味着当你升级 Mongoose 时不仅要看 9.x 的新功能还要注意 8.x/7.x 分支上的修复回移backport。例如8.24.4明确标注了(8.x backport)8.23.0则把flattenUUIDs特性回移到了 8.x 线。当前仓库 package.json 中version为9.9.5与 CHANGELOG 头部条目一致。二、Mongoose 9.0.0一次彻底的大版本重构CHANGELOG 中9.0.0 / 2025-11-21条目集中列出了全部BREAKING CHANGE这是从 8.x 升级时必须逐条核对的内容主要可分为四类。1. 中间件与回调模型的变化彻底移除基于回调的 pre 中间件pre()钩子不再接收next()参数。9.0.0 的迁移指南 docs/migrating_to_9.md 给出了对照写法// Mongoose 8.x不再支持 schema.pre(save, function(next) { // 异步操作 next(); }); // Mongoose 9.xasync/await 或 Promise schema.pre(save, async function() { // 异步操作 }); schema.pre(save, function() { return new Promise((resolve) { // 异步操作 resolve(); }); });验证路径异步化SchemaType.prototype.doValidate()改为返回 Promiseasync function doValidate(value, scope, options)不再接受回调validate()也改为 async 函数并直接调用 Kareem 钩子相关代码见 lib/schemaType.js。移除_executionStack以获得更清晰的错误堆栈移除schemaType.caster/casterConstructor属性改用embeddedSchemaType与Constructor。2. 驱动与依赖升级升级到 MongoDB Node.js Driver v79.0.0随后 9.6.0 升级到 driver 7.2、9.8.0 升级到 driver 7.5package.json 中mongodb: ~7.5与之一致。移除bson直接依赖统一通过mongodb/lib/bson使用 BSON9.9.2 的类型层面也从bson改为从mongodb导入。移除浏览器构建改为独立的mongoosejs/browser包。3. 查询语义收紧findOne(null)、find(null)等直接抛错不再静默返回首条文档。更新管道update pipeline默认禁用向updateOne()/updateMany()/findOneAndUpdate()传入管道数组会抛错必须显式开启updatePipeline: true。FilterQuery属性在 TypeScript 中不再退化为anycreate()与insertOne()参数类型更严格。4. 类型系统与命名修正id从 Document 基类属性改为虚拟属性_id相关类型随之调整。RootQuerySelector、Condition等类型与 MongoDB driver 类型合并统一。复数化修正virus - viruses这也提醒你集合名自动复数化可能出现与旧库不一致的情况。三、9.x 系列值得关注的新特性CHANGELOG 中大量feat前缀条目记录了 9.x 的功能演进以下按模块分类。Schema 与验证strictRead选项9.8.0在文档水合hydration阶段过滤或抛错处理不在 schema 中的字段。源码 lib/document.js 中init()会读取docSchema.options.strictRead当路径类型为adhocOrUndefined且strictRead为throw时抛出StrictModeError为true时直接跳过该字段。对应文档说明见 docs/guide.md 中的strictRead小节。allowNull选项9.6.0即使字段非required也可以禁止null值。实现位于 lib/schemaType.jsrequired: true与allowNull: false同时指定会抛出错误错误消息见 lib/error/messages.js。Union Schema 支持8.18.0 起9.x 持续完善toJSONSchema支持 union、union 的验证与子文档实现以及对 union 应用 create 强转时的基本类型转换。flattenUUIDs选项9.2.0toObject()与toJSON()可展开 UUID8.23.0 已回移。toJSONSchema()完善9.7.1 为 ObjectId 输出 regex 模式、9.4.0 支持 unions、9.9.2 修复 enum 重复null与 object 形式 enum。Model 与查询pathsToSave9.1.0save()仅保存指定路径9.8.0 补充了SaveOptions.pathsToSave类型9.2.2 修正其对所有更新操作符的过滤行为。乐观并发增强9.1.0 增加optimisticConcurrency的 exclude 选项9.4.0/9.8.0/9.9.2 修复了嵌套路径、排除父路径、map 通配符等场景下的版本键处理。returnDocument全局选项9.2.0新增全局returnDocument同时弃用returnOriginal与new9.9.3 文档进一步补充。跳过中间件选项9.2.0可在调用时跳过 middleware 执行对应 issue #15883。bulkSave()完善9.8.0 修复插入新文档时的版本键处理9.9.2 确保事务重试时文档会话被设置9.9.4 按文档 id 索引 bulkSave 写错误以提升性能。hydrate()增强9.2.0 支持strict选项8.19.0 支持virtuals选项。聚合与驱动能力pipelineForUnionWith()9.3.08.24.0 回移复用管道与$unionWith组合TypeScript 友好。Node.js TracingChannel 支持9.7.0为 APM 埋点提供能力实现见 lib/tracing.js使用node:diagnostics_channel。Standard Schema 适配9.7.0为 Model 增加标准 schema 适配器类型层改为使用standard-schema/spec9.7.3与 package.json 依赖一致。四、性能优化路线9.x 的持续调优CHANGELOG 中perf前缀条目在 9.x 后期显著增多形成了一条清晰的性能优化主线toObject()/toJSON()9.9.0 用更快的字符串检查、避免在无 getter 路径上调用isSelected9.9.3 缓存投影元数据、对扁平投影避免扫描全部投影路径。save()链路9.1.2 仅选择_id检查文档存在性9.7.1 减少不必要的 Promise 分配与路径/默认值/脏状态开销9.8.1 避免重复构建 modified paths、避免每次实例化文档都清空 required paths 缓存。insertMany()与变更追踪9.9.0 提升insertMany()与通用变更追踪性能。时间戳9.9.0 除非 upsert 被设置否则不为createdAt添加$setOnInsert。杂项9.8.1 缓存array.unique的toString()结果9.9.2 内联$__hasOnlyPrimitiveValues()中的类型检查8.20.3 使用Object.hasOwn替代hasOwnProperty。这些优化大多伴随对应 issue 编号如 #14394、#16373、#16385在排障时可反向追踪具体提交。五、TypeScript 类型系统的持续演进9.x 的类型工作贯穿始终CHANGELOG 中types(...)前缀条目密集推断能力InferRawDocType/InferHydratedDocType的持续修正子文档、文档数组、嵌套 map、union 分发9.3.3 使MergeType对 union 具有分配性。严格化FilterQuery不再回退到anyexactOptionalPropertyTypes编译支持9.6.2查询过滤类型尊重字符串联合与 enum9.6.0对$and中无法识别的操作符报类型错误9.4.0。文档类型细节id虚拟属性默认加入HydratedDocumenttoObject()保留已 populate 路径除非depopulate: trueModel.schema在省略TSchema时仍保持类型。工具链9.2.2 引入 TSTyche 做类型测试对应脚本test:types见 package.json并逐步替换 tsd。六、典型 Bug 修复模式值得记住的「坑」CHANGELOG 的fix条目是对实际使用最有参考价值的部分几个高频主题值得注意sanitizeFilter 防护8.24.3/9.9.2 将sanitizeFilter应用到countDocuments()与cursor()9.1.6 处理其他顶层查询操作符9.5.0 修复__proto__相关更新与$set方法的误判。原型污染防护9.2.2 修复setDefaultsOnInsert的点号路径处理并防止原型污染9.1.4 防止访问原型上的嵌套路径导致崩溃。数组子文档路径重建8.24.1/9.7.2 在数组重排与删除后重新索引 subdoc保证后续嵌套修改保存到正确路径对应 lib/types/documentArray 相关逻辑。地图Map路径9.9.4 修复移除 map 路径时子路径清理、嵌套路径下 map 的移除以及克隆时 map 值 schematype 的单例保持。optimisticConcurrency与排除路径9.8.0 修复乐观并发下被排除父路径的处理9.9.2 支持 map 通配符。七、文档与生态建设9.x 在文档层面也有不少投入CHANGELOG 记录了新增 Atlas Vector Search 与 Atlas Search 文档9.9.4。生成llms.txt9.7.0并有配套脚本 scripts/generateLLMsTXT.js。加入 MongoDB Knowledge 助手侧边栏9.7.1、深色模式9.0.1、代码块复制按钮8.20.1。大量链接修复与文档重写documents docs 重写、populate 选项补充、sample()示例扩展等。八、升级建议与阅读方法结合 CHANGELOG 与迁移文档推荐的升级路径是先读迁移指南若从 8.x 升级到 9.x通读 docs/migrating_to_9.md更早版本需逐级升级7.x → 8.x → 9.x对应 docs/migrating_to_8.md 等文档。逐条核对 BREAKING CHANGE以 9.0.0 条目的破坏性改动为清单重点检查 pre 中间件next()、更新管道、findOne(null)、id虚拟属性等。关注本版本线的新特性9.8.0 的strictRead、9.6.0 的allowNull、9.2.0 的returnDocument都是可能直接改变业务行为的配置项可结合 docs/guide.md 与 lib/schema.js 的默认值确认行为。把 perf/fix 条目当作升级红利9.x 后期的性能优化toObject、save、insertMany在升级后通常无需改代码即可受益。注意跨分支行为差异8.x 与 9.x 并行的修复如 sanitizeFilter、clone 隔离语义可能不完全一致测试要覆盖两个目标版本。最后升级后建议运行仓库自带的测试体系做验证npm testMocha 全量测试、npm run test:typesTSTyche 类型测试配置见 tstyche.json并在升级前用npm ls mongoose mongodb确认依赖树中没有锁死旧驱动的包。【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考