MongoDB Node.js Driver

MongoDB](https://www.mongodb.com/) 的官方 Node.js 驱动程序。

正在升级到 7 版本？请查看我们的升级指南！

快速链接

站点	链接
文档	www.mongodb.com/docs/drivers/node
API 文档	mongodb.github.io/node-mongodb-native
npm 包	www.npmjs.com/package/mongodb
MongoDB	www.mongodb.com
MongoDB University	learn.mongodb.com
MongoDB 开发者中心	www.mongodb.com/developer
Stack Overflow	stackoverflow.com
源代码	github.com/mongodb/node-mongodb-native
升级到 v7	etc/notes/CHANGES_7.0.0.md
贡献指南	CONTRIBUTING.md
变更日志	HISTORY.md

发布完整性

发布版本会自动创建，并使用 Node 团队的 GPG 密钥 进行签名。作为 GitHub 发布的一部分提供的所有发布包均已签名。要验证提供的包，请下载该密钥并使用 gpg 导入：

gpg --import node-driver.asc

GitHub 发布版本中包含 NPM 包的分离签名文件（名为 mongodb-X.Y.Z.tgz.sig）。

以下命令返回 npm 包的链接。

npm view mongodb@vX.Y.Z dist.tarball

使用上述命令的结果，curl 命令可以返回该版本的官方 npm 包。

要验证下载包的完整性，请运行以下命令：

gpg --verify mongodb-X.Y.Z.tgz.sig mongodb-X.Y.Z.tgz

[!Note] 使用 npm 安装软件包时，不会执行 GPG 验证。GitHub tarball 和 npm 的 tarball 内容完全相同。

发布到 npm registry 的版本还包含 provenance attestation，它在密码学上将软件包与其源仓库和构建工作流关联起来。要验证 provenance：

npm audit signatures

MongoDB Node.js 驱动程序遵循 语义化版本 进行发布。

缺陷 / 功能请求

认为您发现了一个缺陷？希望在 node-mongodb-native 中看到新功能？请在我们的问题管理工具 JIRA 中 创建一个案例：

• 创建一个账户并登录 jira.mongodb.org。
• 导航到 NODE 项目 jira.mongodb.org/browse/NODE。
• 点击 创建问题 - 请尽可能多地提供关于问题类型以及如何复现它的信息。

JIRA 中所有驱动程序项目（即 NODE、PYTHON、CSHARP、JAVA）和 核心服务器（即 SERVER）项目的缺陷报告都是公开的。

支持 / 反馈

对于 Node.js 驱动程序的问题、问题或反馈，请参阅我们的 支持渠道。请勿直接通过电子邮件向任何驱动程序开发人员发送问题或疑问 - 您在 MongoDB 社区论坛 上更有可能得到答复。

变更日志

变更历史可在 HISTORY.md 中找到。

兼容性

该驱动程序目前支持 4.4+ 服务器。

有关详尽的服务器和运行时版本兼容性矩阵，请参阅以下链接：

• MongoDB
• NodeJS

组件支持矩阵

下表描述了 Node.js 驱动程序的附加组件版本兼容性。仅当使用的包版本位于这些支持范围内时，组合使用时才是稳定的。

组件	mongodb@3.x	mongodb@4.x	mongodb@5.x	mongodb@<6.12	mongodb@>=6.12	mongodb@7.x
bson	^1.0.0	^4.0.0	^5.0.0	^6.0.0	^6.0.0	^7.0.0
bson-ext	^1.0.0 || ^2.0.0	^4.0.0	N/A	N/A	N/A	N/A
kerberos	^1.0.0	^1.0.0 || ^2.0.0	^1.0.0 || ^2.0.0	^2.0.1	^2.0.1	^7.0.0
mongodb-client-encryption	^1.0.0	^1.0.0 || ^2.0.0	^2.3.0	^6.0.0	^6.0.0	^7.0.0
mongodb-legacy	N/A	^4.0.0	^5.0.0	^6.0.0	^6.0.0	N/A
@mongodb-js/zstd	N/A	^1.0.0	^1.0.0	^1.1.0	^1.1.0 || ^2.0.0	^7.0.0

Typescript 版本

我们建议使用最新版本的 typescript，但目前我们确保该驱动的公共类型能够针对 typescript@5.6.0 进行编译。 这是保证与我们的驱动兼容的最低 typescript 版本：旧版本可能有效也可能无效 - 使用风险自负。 由于 typescript 不将破坏性更改限制在主版本中，我们将此支持视为尽力而为。 如果您在针对我们支持的 TypeScript 版本时遇到任何意外的编译器故障，请通过在我们的 JIRA 上提交问题来告知我们。

此外，我们的 Typescript 类型与我们最低支持的 Node 版本的 ECMAScript 标准兼容。目前，我们的 Typescript 目标为 es2023。

在自定义运行时中运行

我们正在努力移除 Node.js 作为驱动的依赖项，以便将来可以在非 Node 环境中使用该驱动。 这项工作目前正在进行中，如果您感兴趣，这是 我们的第一个运行时适配器提交。

如果您使用的是非 Node 运行时，请记住以下几点：

1. Webpack/Vite 的用户可能需要阻止 crypto polyfill 注入。
2. 身份验证机制 SCRAM-SHA-1 对 Node.js 有硬性依赖。
3. 身份验证机制 SCRAM-SHA-1 不支持 FIPS 模式。

安装

开始使用 Node.js 驱动的建议方法是使用 npm (Node Package Manager) 在您的项目中安装依赖项。

在您使用 npm init 创建自己的项目后，您可以运行：

npm install mongodb

这将下载 MongoDB 驱动程序，并在您的 package.json 文件中添加一个依赖项条目。

如果您是 Typescript 用户，您需要 Node.js 类型定义才能使用该驱动程序的类型定义：

npm install -D @types/node

驱动程序扩展

MongoDB 驱动程序可以通过以下功能包进行可选增强：

由 MongoDB 维护：

• Zstd 网络压缩 - @mongodb-js/zstd
• MongoDB 字段级和可查询加密 - mongodb-client-encryption
• GSSAPI / SSPI / Kerberos 身份验证 - kerberos

其中一些包包含原生 C++ 扩展。 如果遇到编译问题，请参阅此处的故障排除指南。

第三方：

• Snappy 网络压缩 - snappy
• AWS 身份验证 - @aws-sdk/credential-providers

快速入门

本指南将向您展示如何使用 Node.js 和 MongoDB 设置一个简单的应用程序。其范围仅限于如何设置驱动程序并执行简单的 CRUD 操作。如需更深入的讲解，请参阅官方文档。

创建 package.json 文件

首先，创建一个用于存放应用程序的目录。

mkdir myProject
cd myProject

输入以下命令并回答相关问题，以创建新项目的初始结构：

npm init -y

接下来，将驱动程序作为依赖项安装。

npm install mongodb

启动 MongoDB 服务器

完整的 MongoDB 安装说明，请参阅手册。

1. 从 MongoDB 下载正确的 MongoDB 版本
2. 创建数据库目录（在本例中位于 /data 下）。
3. 安装并启动 mongod 进程。

mongod --dbpath=/data

你应该会看到 mongod 进程启动并打印一些状态信息。

连接到 MongoDB

创建一个新的 app.js 文件，并添加以下代码，以使用 MongoDB 驱动程序尝试一些基本的 CRUD 操作。

添加代码以连接到服务器和数据库 myProject：

注意： 解决 DNS 连接问题

Node.js 18 将默认的 DNS 解析顺序从始终优先 IPv4 更改为 DNS 提供商返回的顺序。在某些环境中，这可能导致 localhost 解析为 IPv6 地址而不是 IPv4，从而导致无法连接到服务器。

可以通过以下方式解决：

• 使用 MongoClient 的 family 选项（MongoClient(<uri>, { family: 4 } )）指定 IP 地址族
• 启用 ipv6 标志启动 mongod 或 mongos（--ipv6 mongod 选项文档）
• 使用 127.0.0.1 作为主机名代替 localhost
• 使用 --dns-resolution-order Node.js 命令行参数指定 DNS 解析顺序（例如 node --dns-resolution-order=ipv4first）

const { MongoClient } = require('mongodb');
// or as an es module:
// import { MongoClient } from 'mongodb'

// Connection URL
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);

// Database Name
const dbName = 'myProject';

async function main() {
  // Use connect method to connect to the server
  await client.connect();
  console.log('Connected successfully to server');
  const db = client.db(dbName);
  const collection = db.collection('documents');

  // the following code examples can be pasted here...

  return 'done.';
}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

在命令行中运行你的应用：

node app.js

应用程序应在控制台打印 Connected successfully to server。

插入文档

在 app.js 中添加以下函数，该函数使用 insertMany 方法向 documents 集合添加三个文档。

const insertResult = await collection.insertMany([{ a: 1 }, { a: 2 }, { a: 3 }]);
console.log('Inserted documents =>', insertResult);

insertMany 命令返回一个包含插入操作信息的对象。

查找所有文档

添加一个返回所有文档的查询。

const findResult = await collection.find({}).toArray();
console.log('Found documents =>', findResult);

此查询返回 documents 集合中的所有文档。 如果您将此代码添加到 insertMany 示例下方，您将看到已插入的文档。

使用查询过滤器查找文档

添加查询过滤器，以仅查找符合查询条件的文档。

const filteredDocs = await collection.find({ a: 3 }).toArray();
console.log('Found documents filtered by { a: 3 } =>', filteredDocs);

仅返回与 'a' : 3 匹配的文档。

更新文档

以下操作会更新 documents 集合中的一个文档。

const updateResult = await collection.updateOne({ a: 3 }, { $set: { b: 1 } });
console.log('Updated documents =>', updateResult);

该方法通过向文档添加一个新字段 b 并将其设置为 1，来更新字段 a 等于 3 的第一个文档。updateResult 包含关于是否存在匹配文档进行更新的信息。

删除文档

删除字段 a 等于 3 的文档。

const deleteResult = await collection.deleteMany({ a: 3 });
console.log('Deleted documents =>', deleteResult);

索引集合

索引 可以提升您的应用程序 性能。以下函数在 documents 集合的 a 字段上创建索引。

const indexName = await collection.createIndex({ a: 1 });
console.log('index name =', indexName);

有关更详细的信息，请参阅 索引策略页面。

错误处理

如果你需要从我们的驱动程序中过滤某些错误，我们在 etc/notes/errors.md 中描述了一个有用的错误树。

我们建议对错误使用 instanceof 检查，并避免在代码中依赖解析 error.message 和 error.name 字符串。 我们保证 instanceof 检查将根据 semver 指南通过，但错误可能会被细分为子类，或者其消息可能会随时更改，即使是补丁版本，只要我们认为这样能增加错误的有用性。

我们添加到驱动程序中的任何新错误都将直接继承自现有的错误类，并且除非在主要版本发布中，否则现有的错误不会被移动到不同的父类。 这意味着 instanceof 将始终能够准确捕获我们驱动程序抛出的错误。

const client = new MongoClient(url);
await client.connect();
const collection = client.db().collection('collection');

try {
  await collection.insertOne({ _id: 1 });
  await collection.insertOne({ _id: 1 }); // duplicate key error
} catch (error) {
  if (error instanceof MongoServerError) {
    console.log(`Error worth logging: ${error}`); // special case for some reason
  }
  throw error; // still want to crash
}

夜间版本

如果你需要使用来自最新 main 分支的更改进行测试，我们的 mongodb npm 包会在 nightly 标签下发布夜间版本。

npm install mongodb@nightly

Nightly 版本无论测试结果如何都会发布。 这意味着可能存在语义破坏或仅部分实现的功能。 Nightly 构建不适合用于生产环境。

实验性功能

MongoDB Node.js 驱动程序提供了前沿的实验性功能，让您能够提前访问新的功能和 API。这些功能以 @experimental 标签标记，非常适合探索新功能并提供 反馈。

实验性功能不受 语义化版本控制 规则的约束，因此任何未来版本中都可能发生破坏性变更或移除。不建议在生产环境中使用这些功能。

在 EXPERIMENTAL_FEATURES.md 中探索完整的实验性功能列表，其中包含描述和使用示例。

后续步骤

• MongoDB 文档
• MongoDB Node 驱动程序文档
• 阅读有关 Schemas 的内容
• 在 GitHub 上为我们点星

许可证

Apache 2.0

© 2012-present MongoDB 贡献者
© 2009-2012 Christian Amor Kvalheim