Mongoose

Mongoose 是一款 MongoDB 对象建模工具，专为异步环境而设计。Mongoose 支持 Node.js 和 Deno（alpha 版本）。

文档

官方文档网站为 mongoosejs.com。

Mongoose 9.0.0 已于 2025 年 11 月 21 日发布。您可以访问我们的文档站点了解 9.0.0 版本中向后不兼容变更的更多详情。

支持

• Stack Overflow
• Bug 报告
• Mongoose Slack 频道
• 帮助论坛
• MongoDB 支持

插件

访问插件搜索站点，查看社区中数百个相关模块。接下来，通过文档或这篇博客文章学习如何编写自己的插件。

贡献者

欢迎提交 Pull Request！请基于 master 分支提交 Pull Request，并遵循贡献指南。

如果您的 Pull Request 包含文档修改，请不要改动任何 .html 文件。.html 文件为编译产物，请将修改提交至 docs/*.pug、lib/*.js 或 test/docs/*.js 中。

查看全部 400 余位贡献者。

安装指南

首先安装 Node.js 和 MongoDB，然后使用你偏好的包管理器安装 mongoose 包：

使用 npm 安装

npm install mongoose

使用 pnpm

pnpm add mongoose

使用 Yarn

yarn add mongoose

使用 Bun

bun add mongoose

Mongoose 6.8.0 还包含了对 Deno 的 alpha 版本支持。

导入

// Using Node.js `require()`
const mongoose = require('mongoose');

// Using ES6 imports
import mongoose from 'mongoose';

或者，也可以使用 Deno 的 createRequire() 以支持 CommonJS，具体如下。

import { createRequire } from 'https://deno.land/std@0.177.0/node/module.ts';
const require = createRequire(import.meta.url);

const mongoose = require('mongoose');

mongoose.connect('mongodb://127.0.0.1:27017/test')
  .then(() => console.log('Connected!'));

然后，您可以使用以下命令运行上述脚本。

deno run --allow-net --allow-read --allow-sys --allow-env mongoose-test.js

Mongoose Studio

Mongoose Studio 是由 Mongoose 团队为已使用 Mongoose 的应用打造的一款免费、完全开源的基于浏览器的 MongoDB 图形化管理工具。通过 npm 安装 @mongoosejs/studio，即可将其作为 Express 中间件与你的应用一同运行，或部署到 Vercel 和 Netlify 上。它支持浏览和编辑文档、使用现有模型和模式进行带自动补全的查询、构建仪表盘、可视化和编辑 GeoJSON，以及运用 AI 辅助的 MongoDB 工作流，而无需将数据迁移到第三方托管工作区，也无需共享原始的 MongoDB 连接字符串。

Mongoose for Enterprise

作为 Tidelift 订阅的一部分提供

mongoose 及其他数千个软件包的维护者正与 Tidelift 合作，为你构建应用所依赖的开源依赖项提供商业支持与维护服务。在为你实际使用的依赖项维护者提供报酬的同时，节省时间、降低风险并改善代码质量。了解更多。

概述

连接 MongoDB

首先，我们需要定义一个连接。如果你的应用只使用一个数据库，应使用 mongoose.connect。如果需要创建额外的连接，请使用 mongoose.createConnection。

connect 和 createConnection 都接受 mongodb:// URI，或 host, database, port, options 参数。

await mongoose.connect('mongodb://127.0.0.1/my_database');

连接成功后，Connection实例上会触发open事件。如果使用mongoose.connect方式连接，那么Connection指的就是mongoose.connection。否则，mongoose.createConnection的返回值即为一个Connection。

注意： 如果本地连接失败，请尝试使用127.0.0.1代替localhost。有时本地主机名被修改后可能会出现问题。

重要提示！ Mongoose会缓冲所有命令，直到成功连接数据库。这意味着您无需等待连接MongoDB完成，就可以提前定义模型、执行查询等操作。

定义模型

模型通过Schema接口进行定义。

const Schema = mongoose.Schema;
const ObjectId = Schema.ObjectId;

const BlogPost = new Schema({
  author: ObjectId,
  title: String,
  body: String,
  date: Date
});

除了定义文档的结构以及存储的数据类型之外，Schema 还负责以下内容的定义：

• 校验器（异步和同步）
• 默认值
• 获取器
• 设置器
• 索引
• 中间件
• 方法定义
• 静态方法定义
• 插件
• 伪 JOIN

下面的示例展示了其中部分功能：

const Comment = new Schema({
  name: { type: String, default: 'hahaha' },
  age: { type: Number, min: 18, index: true },
  bio: { type: String, match: /[a-z]/ },
  date: { type: Date, default: Date.now },
  buff: Buffer
});

// a setter
Comment.path('name').set(function(v) {
  return capitalize(v);
});

// middleware
Comment.pre('save', function(next) {
  notify(this.get('email'));
  next();
});

访问模型

通过 mongoose.model('ModelName', mySchema) 定义模型后，我们可以使用相同的函数来访问它。

const MyModel = mongoose.model('ModelName');

或者直接一步到位

const MyModel = mongoose.model('ModelName', mySchema);

第一个参数是你模型所对应集合的单数名称。Mongoose 会自动查找你模型名称的复数形式。 例如，如果你使用

const MyModel = mongoose.model('Ticket', mySchema);

然后 MyModel 将使用 tickets 集合，而不是 ticket 集合。更多细节请参阅 模型文档。

一旦我们有了模型，就可以实例化它并保存：

const instance = new MyModel();
instance.my.key = 'hello';
await instance.save();

或者，我们可以从同一集合中查找文档。

await MyModel.find({});

您还可以使用 findOne、findById、update 等方法。

const instance = await MyModel.findOne({ /* ... */ });
console.log(instance.my.key); // 'hello'

更多详情请参阅文档。

重要提示！ 如果您通过mongoose.createConnection()创建了独立连接，但仍尝试通过mongoose.model('ModelName')访问模型，由于该模型并未关联到活动的数据库连接，因此将无法按预期工作。在这种情况下，请通过您创建的连接来访问模型：

const conn = mongoose.createConnection('your connection string');
const MyModel = conn.model('ModelName', schema);
const m = new MyModel();
await m.save(); // works

vs

const conn = mongoose.createConnection('your connection string');
const MyModel = mongoose.model('ModelName', schema);
const m = new MyModel();
await m.save(); // does not work b/c the default connection object was never connected

内嵌文档

在第一个示例代码片段中，我们在Schema中定义了一个键，其形式如下：

comments: [Comment]

其中 Comment 是我们创建的 Schema。这意味着创建嵌入式文档就像这样简单：

// retrieve my model
const BlogPost = mongoose.model('BlogPost');

// create a blog post
const post = new BlogPost();

// create a comment
post.comments.push({ title: 'My comment' });

await post.save();

删除它们也是如此：

const post = await BlogPost.findById(myId);
post.comments[0].deleteOne();
await post.save();

嵌入式文档拥有与模型完全相同的全部特性：默认值、校验器、中间件。

中间件

参见文档页面。

拦截并修改方法参数

你可以通过中间件拦截方法参数。

例如，以下操作可以让你在文档中某个路径被set为新值时，广播关于该文档的变更：

schema.pre('set', function(next, path, val, typel) {
  // `this` is the current Document
  this.emit('set', path, val);

  // Pass control to the next pre
  next();
});

此外，您可以修改传入的 method 参数，使得后续的中间件看到不同的参数值。为此，只需将新值传给 next：

schema.pre(method, function firstPre(next, methodArg1, methodArg2) {
  // Mutate methodArg1
  next('altered-' + methodArg1.toString(), methodArg2);
});

// pre declaration is chainable
schema.pre(method, function secondPre(next, methodArg1, methodArg2) {
  console.log(methodArg1);
  // => 'altered-originalValOfMethodArg1'

  console.log(methodArg2);
  // => 'originalValOfMethodArg2'

  // Passing no arguments to `next` automatically passes along the current argument values
  // i.e., the following `next()` is equivalent to `next(methodArg1, methodArg2)`
  // and also equivalent to, with the example method arg
  // values, `next('altered-originalValOfMethodArg1', 'originalValOfMethodArg2')`
  next();
});

Schema 使用陷阱

在 Mongoose 的 Schema 中，type 具有特殊含义。如果你的 Schema 需要将 type 作为嵌套属性使用，则必须采用对象字面量的写法：

new Schema({
  broken: { type: Boolean },
  asset: {
    name: String,
    type: String // uh oh, it broke. asset will be interpreted as String
  }
});

new Schema({
  works: { type: Boolean },
  asset: {
    name: String,
    type: { type: String } // works. asset is an object with a type property
  }
});

驱动访问

Mongoose 基于官方 MongoDB Node.js 驱动程序构建。每个 mongoose 模型都持有对原生 MongoDB 驱动程序集合的引用。该集合对象可通过 YourModel.collection 访问。然而，直接使用集合对象会绕过 mongoose 的所有功能，包括钩子（hooks）、验证（validation）等。一个值得注意的例外是，YourModel.collection 仍然会对命令进行缓冲。因此，YourModel.collection.find() 不会返回游标（cursor）。

API 文档

Mongoose API 文档，由 dox 和 acquit 生成。

相关项目

MongoDB 运行工具

• run-rs
• mongodb-memory-server
• mongodb-topology-manager

非官方 CLI 工具

• mongoosejs-cli

数据填充

• dookie
• seedgoose
• mongoose-data-seed

Express 会话存储

• connect-mongodb-session
• connect-mongo

许可证

版权所有 (c) 2010 LearnBoost <dev@learnboost.com>

特此免费授予任何获得本软件及相关文档文件（以下简称"软件"）副本的人士，在不受任何限制的情况下处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向获得本软件的人士提供本软件，但须满足以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

本软件按"原样"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性及不侵权的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为或其他方面，均由本软件或本软件的使用或其他交易引起，或与之相关。