/ /

指定连接选项

本部分介绍 Node.js驱动程序支持的MongoDB连接和身份验证选项，您可以在 MongoClientOptions实例中设立这些选项。

For more information on setting connection options directly in a connection string, see Connection Strings in the MongoDB Server manual.

名称	接受的值	默认值	说明
appName	字符串	`null`	指定驱动程序在连接握手过程中传递到客户端元数据中的服务器的应用名称。当建立此连接时，驱动程序会向 MongoDB 发送 `appName` 值。此值将记录在日志文件、慢速查询日志和配置文件集合中。
authMechanism	字符串	`null`	指定用于连接到服务器的身份验证机制方法。如果不指定值，驱动程序将使用默认机制，即 `SCRAM-SHA-1` 或 `SCRAM-SHA-256`，具体取决于服务器版本。有关可用的身份验证机制，请参阅身份验证机制部分。
authMechanismProperties	逗号分隔的键值对，例如 "opt1:val1,opt2:val2"	`null`	指定为身份验证提供的其他选项，例如为 GSSAPI 启用主机名规范化。
authSource	字符串	`null`	指定连接要对其进行身份验证的数据库。
autoSelectFamily	布尔	`true`	如果设立为 `true`，套接字将尝试连接 IPv6 和 IPv4 地址，直到建立连接。如果可用，驱动程序将选择第一个 IPv6解决。
autoSelectFamilyAttemptTimeout	non-negative integer	`null`	指定使用 `autoSelectFamily` 选项时，在尝试下一个解决之前等待连接尝试完成的时间（以毫秒为单位）。如果设立为小于 `10` 的正整数，则使用值 `10`。
compressors	逗号分隔的字符串列表，例如 "snappy,zlib,zstd"	`null`	指定发送到服务器或从服务器接收的传输协议消息的允许压缩类型。请参阅网络压缩，获取更多信息。
connectTimeoutMS	non-negative integer	`30000`	指定在引发错误之前等待与服务器建立单个 TCP 套接字连接的时间（以毫秒为单位）。指定 `0` 意味着应用程序在建立套接字时设置无限套接字超时。
directConnection	布尔	`false`	指定是否强制将所有操作分派到连接 URI 中指定的主机。
enableUtf8Validation	布尔	`true`	指定 `true` 可启用该连接的 UTF-8 验证。当 MongoDB 尝试将包含无效 UTF-8 字符的字符串数据序列化为 BSON 时，会抛出错误。这适用于文档键和文档值，此验证增加了处理开销。指定 `false` 可禁用该连接的 UTF-8 验证。当数据包含无效的 UTF-8 数据时，MongoDB 不会抛出错误。如果禁用验证，则应用程序将避免验证处理开销。在禁用验证的情况下编辑数据可能会导致数据丢失。禁用 UTF-8 验证是一种临时解决方法，仅用于查询或导出数据。要学习；了解有关 UTF-8 字符的更多信息，请参阅维基百科上的 UTF-8 。
heartbeatFrequencyMS	大于或等于 500 的整数。	`null`	指定服务器定期监控检查的间隔时间（以毫秒为单位）。
loadBalanced	布尔	`null`	指定驱动程序是否连接到负载均衡器。
localThresholdMS	non-negative integer	`15`	指定用来在合适的服务器之间进行选择的往返时间的延迟窗口大小（以毫秒为单位）。指定 `0` 意味着无需等待，即可用的最快服务器。
maxIdleTimeMS	non-negative integer	`0`	指定连接在关闭之前可以处于空闲状态的时间（以毫秒为单位）。指定 `0` 意味着没有最小值。
maxPoolSize	non-negative integer	`100`	指定驱动程序可在连接池中创建的客户端或连接的最大数量。此数量包括正在使用的连接。
maxConnecting	non-negative integer	`2`	指定驱动程序的连接池可以同时建立的最大连接数。
maxStalenessSeconds	-1，或大于或等于 90 的整数	`null`	指定从节点可能遇到但仍有资格供服务器选择的最大复制延迟（以挂钟时间为单位）。指定 `-1` 意味着没有最大值。
minPoolSize	non-negative integer	`0`	指定驱动程序在连接池中创建并维持的连接数。即使没有发生任何操作，连接池中也要保持这一连接数。此数量包括正在使用的连接。
proxyHost	字符串	`null`	指定 SOCKS5 代理的 IPv4 地址、IPv6 地址或域名。
代理端口	non-negative integer	`null`	指定 SOCKS5 代理服务器的 TCP 端口号。如果设置了 `proxyHost` 选项，则此选项的值默认为 `1080`。
proxyUsername	字符串	`null`	指定用于向 SOCKS5 代理服务器进行身份验证的用户名。如果将此选项设置为零长度的字符串，驱动程序将忽略它。
proxyPassword	字符串	`null`	指定用于向 SOCKS5 代理服务器进行身份验证的密码。如果将此选项设置为零长度的字符串，驱动程序将忽略它。
readConcernLevel	字符串	`null`	指定客户端的默认读关注。有关更多信息，请参阅读关注。
readPreference	字符串	`"primary"`	指定客户端的默认读取偏好（不包括标记）。有关更多信息，请参见读取偏好。
readPreferenceTags	逗号分隔的键:值对，例如 "dc:ny,rack:1"，而且 "dc:ny" 可以指定多次，该键的每个实例都是一个单独的标记集	`null`	指定客户端的默认读取偏好标记。仅当读取偏好不是主节点（"primary"）模式时，此选项才有效。驱动程序将 URI 中标记的顺序用作读取偏好的顺序。
replicaSet	字符串	`null`	指定要连接到的副本集的名称。
retryReads	布尔	`true`	允许重试读取。
retryWrites	布尔	`true`	启用可重试写入。
serverMonitoringMode	`auto`, `stream` , `poll`	`auto`	指定驱动程序监控器使用的监控模式。当此选项设置为 `auto` 时，监控模式由驱动程序运行的环境决定。该驱动程序在功能即服务 (FaaS) 环境中使用轮询模式，在其他环境中使用流媒体模式。
serverSelectionTimeoutMS	non-negative integer	`30000`	指定在抛出错误之前，为服务器选择阻塞的超时时间（以毫秒为单位）。
socketTimeoutMS	non-negative integer	`0`	指定超时之前尝试在套接字上发送或接收所花费的时间（以毫秒为单位）。指定 `0` 意味着应用程序在建立套接字时设置无限套接字超时。
SrvMaxHosts	non-negative integer	`0`	指定最初填充种子列表，或在 SRV 轮询期间向拓扑结构中添加新主机时，随机选择的 SRV 结果的最大数量。
srvServiceName	根据 RFC 的有效 SRV 服务名称6335	`"mongodb"`	指定在初始 DNS 种子列表发现中用于 SRV 查找的服务名称。
ssl	布尔	`false`	`ssl` 是 `tls` 选项的别名。
TLS	布尔	`false`	指定与服务器的连接是否需要 TLS。使用 `"mongodb+srv"` 的 `srvServiceName` 或指定其他 `tls` 前缀选项会将 `tls` 的值隐式设置为 `true`。
tlsAllowInvalidCertificates	布尔	`false`	指定当服务器的 TLS 证书无效时，驱动程序是否产生一个错误。将此选项设置为 `true`（仅用于测试目的）。
tlsAllowInvalidHostnames	布尔	`false`	指定当服务器主机名与 TLS 证书指定的主机名匹配时，驱动程序是否会生成错误。将此选项设为 `true` 以仅供测试之用。
tlsCAFile	字符串	`null`	指定一个文件的路径，此文件中包含建立 TLS 连接时要信任的单个或一组证书颁发机构。要了解有关如何设置此连接选项的更多信息，请参阅 TLS 指南的提供证书文件路径部分。
tlsCertificateKeyFile	字符串	`null`	指定客户端证书文件或客户端私钥文件的路径。如果同时需要这两份文件，则必须将它们合并起来。要了解设置此连接选项的更多信息，请参阅 TLS 指南的提供证书文件路径部分。
tlsCertificateKeyFilePassword	字符串	`null`	指定密码，该密码负责解密用于 TLS 连接的客户端私钥。
tlsInsecure	布尔	`false`	指定尽可能放宽 TLS 约束，如允许无效证书或主机名不匹配。将此选项设置为`true`，仅供测试之用。
waitQueueTimeoutMS	non-negative integer	`0`	指定在被判定超时之前，尝试从服务器的连接池中获取一个连接所允许花费的最长时间（以毫秒为单位）。 `0` 表示没有超时。
zlibCompressionLevel	介于 `-1` 和 `9`（含）之间的整数	`-1`	指定使用 zlib 压缩传输协议消息时的压缩级别。`-1` 表示默认级别，`0` 表示不压缩，`1` 表示最快速度，`9` 则表示最佳压缩级别。请参阅网络压缩以了解更多信息。

连接超时选项

设置	说明
connectTimeoutMS	`connectTimeoutMS` is a connection option that sets the time, in milliseconds, for an individual connection from your connection pool to establish a TCP connection to the MongoDB Server before timing out. To modify the allowed time for MongoClient.connect to establish a connection to a MongoDB Server, use the `serverSelectionTimeoutMS` option instead. 默认值：30000
socketTimeoutMS	`socketTimeoutMS` 指定驱动程序在关闭不活动套接字前的等待时间。默认值是永不使套接字超时。此选项仅适用于已连接的套接字。
maxTimeMS	maxTimeMS specifies the maximum amount of time that the server waits for an operation to complete after it has reached the server. If an operation runs over the specified time limit, it returns a timeout error. You can pass `maxTimeMS` only to an individual operation or to a cursor.

如需指定 MongoClient 的可选设置，请在构造函数的 options 对象中声明一个或多个可用设置，如下所示：

const client = new MongoClient(uri, {
  connectTimeoutMS: 2000,
  socketTimeoutMS: 2000,
});

要查看所有可用设置，请参阅 MongoClientOptions API 文档。

要指定 maxTimeMS，请将其作为选项传递给单个操作：

const filter = {};
const result = await collection.distinct('my-key', filter, {
  maxTimeMS: 50,
});

连接后关闭套接字

如果您遇到意外的网络行为，或者MongoDB进程因错误而失败，您可能不会收到驱动程序正确关闭相应套接字的确认信息。

为确保驱动程序在这些情况下正确关闭套接字，请设置 socketTimeoutMS 选项。当 MongoDB 进程超时时，驱动程序将关闭套接字。我们建议您选择的 socketTimeoutMS 的值应比应用程序执行最慢操作的预期持续时间长两到三倍。

防止长时间运行的操作拖慢服务器速度

您可以通过指定超时值来防止长时间运行的操作拖慢服务器。您可以将 maxTimeMS() 方法链接到单个操作，为特定动作设立超时。

以下示例展示如何将 maxTimeMS() 方法链接到 find() 操作，该操作会返回一个游标：

const cursor = collection.find({ name: 'a' }).maxTimeMS(5000);

keepAlive 连接选项

The keepAlive connection option specifies whether to enable Transmission Control Protocol (TCP) keepalives on a TCP socket. If you enable keepalives, the driver checks whether the connection is active by sending periodic pings to your MongoDB deployment. This functionality works only if your operating system supports the SO_KEEPALIVE socket option.

keepAliveInitialDelay 选项指定了驱动程序在启动 keepalive 之前等待的毫秒数。

5.3 驱动程序版本已弃用这些选项。从驱动程序 6.0 版开始，keepAlive 选项永久设置为 true，keepAliveInitialDelay 设置为 300000 毫秒（300 秒）。

警告

如果您的防火墙忽略或删除了 keepalive 消息，您可能无法识别删除的连接。

指定连接选项

连接超时选项

连接后关闭套接字

防止长时间运行的操作拖慢服务器速度

keepAlive 连接选项

更多信息