客户端库兼容性表 - 客户端库

提示

要了解如何下载 C 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了C驱动程序和MongoDB Server之间的兼容性：

C 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
2.5	✓	✓	✓	✓	✓	✓	✓
2.3 到 2.4	⊛	✓	✓	✓	✓	✓	✓
1.28 到 2.2		✓	✓	✓	✓	✓	✓
1.24 到 1.27		⊛	✓	✓	✓	✓	✓
1.22 到 1.23		⊛	⊛	✓	✓	✓	✓
1.19 到 1.21		⊛	⊛	⊛	✓	✓	✓
1.18		⊛	⊛	⊛	✓ [1]	✓	✓
1.17		⊛	⊛	⊛	⊛	✓	✓
1.15 到 1.16		⊛	⊛	⊛	⊛	⊛	✓
1.11 到 1.14		⊛	⊛	⊛	⊛	⊛	⊛

[1]	1.18 驱动程序不支持从节点上的快照读取。有关详细信息，请参阅 MongoDB Server 版本 5.0 发布说明。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。2.3 和 2.4 之间的所有 C 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于C驱动程序，这包括版本 2.5 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用C驱动程序版本 1.28 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 2.5 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月之前的所有 C 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

C语言兼容性

本部分介绍了 C 驱动程序版本和 C 版本之间的兼容性。单元格中的复选标记 (✓) 表示 C 驱动程序版本与 C 版本完全兼容。空白单元格表示组合不兼容或未经测试。

下表显示了C驱动程序和C语言之间的兼容性：

C 驱动程序版本	C17/C18	C11	C99	C89
1.24 到 2.5	✓	✓	✓
<= 1.23		✓	✓	✓

平台兼容性

本部分显示有关C驱动程序支持的平台和工具链的兼容性信息。

操作系统

我们预计以下操作系统支持使用C驱动程序：

操作系统	注意
Debian	11.0 及更高版本
RHEL	7.0 及更高版本。支持相同发布版本的 RHEL 衍生版本（例如CentOS、 Rocky Linux和 AlmaLinux ）。Fedora 也受支持。
Ubuntu	20.04 及更高版本。基于受支持Ubuntu版本的Ubuntu衍生版本也受支持。
Arch Linux
macOS	C 驱动程序 2.1 及更早版本需要 macOS 11.0 或更高版本。 C 驱动程序 2.2 及更高版本需要 macOS 14.0 或更高版本。
Windows	Windows Server 2008 及更高版本

编译器

以下编译器不断使用C驱动程序进行测试：

编译器	注意
Clang	版本 3.7、3.8 和 6.0。还支持较新的版本以及相应的 Apple Clang 版本。
GNU 编译器集合 (GCC)	版本 4.8、5.4、6.3、7.5、8.2、8.3、 9.4 和 10.2。 MinGW-w64 GCC 也经过测试并受支持。
Microsoft Visual C++ (MSVC)	使用 15.x (Visual Studio 2017) 进行测试。支持较新的 MSVC 版本，但尚未测试。

架构

以下 CPU 架构持续使用C驱动程序进行测试：

架构	注意
x 86 （ 32位）	仅在Windows上测试
x 86 _ 64 （ 64位 x 86 ）	已在 Linux、macOS 和 Windows 上测试
ARM / aarch 64	已在 macOS 和 Linux 上测试
Power 8 （ppc 64文件）	仅在Linux上测试
IBM Z Series (s390x)	仅在Linux上测试

其他平台

其他平台和工具链未经测试，但我们预计上述平台的类似版本也能正常运行。如果您遇到预期可以运行的平台或工具链，但发现它不起作用，请打开描述问题的 Jira 问题，或打开GitHub 拉取请求来修复它。

重要

欢迎使用简单的拉取请求来修复不支持的平台，但会根据具体情况予以考虑。合并拉取请求以修复不受支持的平台上的库并不意味着完全支持该平台。

提示

要了解如何下载 C++ 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了C++驱动程序和MongoDB Server之间的兼容性：

C++ 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
4.6	✓	✓	✓	✓	✓	✓
4.3 到 4.5	⊛	✓	✓	✓	✓	✓
4.2		✓	✓	✓	✓	✓
3.11 到 4.1		✓	✓	✓	✓	✓	✓
3.8 到 3.10		⊛	✓	✓	✓	✓	✓
3.7		⊛	⊛	⊛	✓	✓	✓
3.6		⊛	⊛	⊛	⊛	✓	✓
3.4 到 3.5		⊛	⊛	⊛	⊛	⊛	⊛

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。4.3 和 4.5 之间的所有 C++ 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于C++驱动程序，这包括版本 4.6 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用C++驱动程序版本 3.11 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 4.6 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已寿命结束，截至 2029月日。截至 8 月 2032 的所有 C++ 驱动程序发布将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

C++兼容性

本节介绍 C++ 驱动程序版本与 C++ 版本之间的兼容性。单元格中的对号（✓）表示 C++ 驱动程序版本与 C++ 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

下表显示了C++和MongoDB Server之间的兼容性：

C++ 驱动程序版本	C++23	C++20	C++17	C++14	C++11
3.8 到 4.6	✓	✓	✓	✓	✓
3.0 到 3.7			✓	✓	✓

libmongoc 兼容性

下表显示了每个版本的C++驱动程序的最低 libmongoc 版本：

C++ 驱动程序版本	最低 libmongoc 版本
4.6 .x	2.5.6
4.5 .x	2.3.3
4.4.x	2.3.1
4.3 .x	2.3.0
4.2.x	2.2.3
4.1 .x	2.0.0
4.0.x	1.29.0
3.11 .x	1.28.0
3.9.x 和 3.10.x	1.25.0
3.8 .x	1.24.0
3.7 .x	1.22.1
3.6.x	1.17.0
3.5 .x	1.15.0
3.4.x	1.13.0
3.3 .x	1.10.0
3.2 .x	1.9.2
3.1.4	1.7.0
3.1.0 至 3.1.3	1.5.0
3.0.1 至 3.0.3	1.3.4
3.0.0	1.3.1

编译器兼容性

C++驱动程序支持以下编译器：

GCC v8.1或更高版本
Clang v3.8或更高版本
Xcode v13.1或更高版本
Visual Studio 2017 版本 15.9 或更高版本

注意

上述编译器版本是从源代码构建C++驱动程序所需的最低版本。这些不是使用预构建标头和库的要求。

提示

要了解如何下载 .NET/C# 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了.NET/C#驱动程序和MongoDB Server之间的兼容性：

.NET/C# 驱动程序版本	MongoDB 9.0	MongoDB 8.2 至 8.3	MongoDB 8.1	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
3.10 到 3.12	✓	✓	✓	✓	✓	✓	✓	✓
3.8 到 3.9	⊛	✓	✓	✓	✓	✓	✓	✓	✓
2.29 到 3.7		⊛	✓	✓	✓	✓	✓	✓	✓
2.20 到 2.28		⊛	⊛	⊛	✓	✓	✓	✓	✓
2.16 到 2.19		⊛	⊛	⊛	⊛	✓	✓	✓	✓
2.15		⊛	⊛	⊛	⊛	⊛	✓	✓	✓
2.7 到 2.14		✗ [2]	✗ [2]	⊛	⊛	⊛	⊛	✓	✓
2.0 到 2.6		✗ [2]	✗ [2]						✓

[2]	（1、2、3、4）由于身份验证问题，这些驾驶员版本与MongoDB Server 8.1 或更高版本不兼容。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。3.8 和 3.9 之间的所有 .NET/C# 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于.NET/C#驱动程序，这包括版本 3.10 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用.NET/C#驱动程序版本 2.29 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 3.10 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月之前的所有 .NET/C# 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

C#兼容性

本节介绍了 .NET/C# 驱动程序的版本与 .NET 或 .NET 框架的版本之间的兼容性。单元格中的对号（√）表示 .NET/C# 驱动程序版本与 .NET 或 .NET 框架版本完全兼容。空单元格表示该组合不兼容或未经过测试。

.NET

下表显示了.NET/C#驱动程序和.NET之间的兼容性：

.NET/C# 驱动程序版本	.NET 10	.NET 8	.NET 7	.NET 6	.NET 5	.NET Core 3 .X	.NET Core 2 .X
3.5.2 至 3.12	✓	✓	✓	✓	✓	✓
3.0 至 3.5.1		✓	✓	✓	✓	✓
2.3 到 2.30		✓	✓	✓	✓	✓	✓

.NET Framework

下表显示了 .NET/C# 驱动程序与 .NET 框架之间的兼容性：

.NET/C# 驱动程序版本	.NET 4.8	.NET 4.7	.NET 4.6
2.14 至 3.12 [3]	✓	✓
2.0 到 2.13	✓	✓	✓

[3]	驱动程序版本 2.14 及更高版本需要.NET Framework 4.7.2 或更高版本。

提示

要了解如何下载 Entity Framework Core 提供商并创建第一个应用程序，请参阅开始使用。

实体框架核心兼容性

The major version of the MongoDB Entity Framework Core Provider must match the major version of Entity Framework Core that your application uses. For example, if your application uses Entity Framework Core 8.x, you must use version 8.x of the MongoDB Entity Framework Core Provider.

MongoDB Server 兼容性

实体框架核心提供商需要MongoDB Server 5.0 或更高版本。

.NET兼容性

实体框架 8.x 和 9.x 提供程序需要.NET 8.0 或更高版本。

实体框架 10.x提供商需要.NET 10.0 或更高版本。

提示

要了解如何下载 Go 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Go驱动程序和MongoDB Server之间的兼容性：

Go 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.1	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
2.9	✓	✓	✓	✓	✓	✓	✓
2.6 到 2.8	⊛	✓	✓	✓	✓	✓	✓	✓
2.1 到 2.5		✓	✓	✓	✓	✓	✓	✓
1.12 到 2.0		⊛ [4]	✓	✓	✓	✓	✓	✓
1.11		⊛	⊛	✓	✓	✓	✓	✓

[4]	Go驱动程序v1.17 和 v2.0 与MongoDB Server 8.0 部分兼容，但不支持客户端批量写入。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。2.6 和 2.8 之间的所有版本的 Go 驱动程序都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Go驱动程序，这包括版本 2.9 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用Go驱动程序版本 2.1 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 2.9 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月之前发布的所有 Go 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Go兼容性

Go驱动程序需要Go 1.25 或更高版本。

提示

要了解如何下载 Java Sync Driver 并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Java驱动程序和MongoDB Server之间的兼容性：

Java 驱动程序版本	MongoDB 9.0	MongoDB 8.3	MongoDB 8.1 至 8.2	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
5.12 到 5.13	✓	✓	✓	✓	✓	✓	✓	✓	✓
5.9 到 5.11	⊛	✓	✓	✓	✓	✓	✓	✓	✓
5.8		✓	✓	✓	✓	✓	✓	✓	✓
5.2 到 5.7		⊛	✓	✓	✓	✓	✓	✓	✓
4.10 到 5.1		⊛	⊛	⊛	✓	✓	✓	✓	✓
4.8 到 4.9		⊛	⊛	⊛	⊛	✓	✓	✓	✓
4.7		⊛	⊛	⊛	⊛	✓	✓	✓	✓
4.3 到 4.6		⊛	⊛	⊛	⊛	⊛	✓	✓	✓
4.1 到 4.2		⊛	⊛	⊛	⊛	⊛	⊛	✓	✓
4.0		⊛	⊛	⊛	⊛	⊛	⊛	⊛	⊛
3.11 到 3.12		✗ [5]	✗ [5]	⊛	⊛	⊛	⊛	⊛	⊛
3.8 到 3.10		✗ [5]	✗ [5]	⊛	⊛	⊛	⊛	⊛	⊛

[5]	（1、2、3、4）由于身份验证问题，这些驾驶员版本与MongoDB8.1 或更高版本不兼容。要学习；了解更多信息，请参阅升级驱动程序版本。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。5.9 和 5.11 之间的所有 Java 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Java驱动程序，这包括版本 5.12 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果您要升级到MongoDB Server 8.0，则可以使用Java驱动程序版本 5.2 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 5.12 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。截至 2032 年 8 月的所有 Java 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Java兼容性

本节介绍了 Java 驱动程序的版本与 Java 的版本之间的兼容性。单元格中的对号（✓）表示 Java 驱动程序版本与 Java 版本完全兼容。空白单元格表示组合不兼容或未经过测试。

从 Java 8 开始，该表仅列出长期支持 (LTS) Java 版本。驱动程序通过 Java 虚拟机 (JVM) 向后兼容性支持所有晚于 Java 8 的版本。

Java 驱动程序版本	Java 21	Java 17	Java 11	Java 8	Java 7	Java 6
4.11 到 5.13	✓	✓	✓	✓
4.5 到 4.10	✓ [6]	✓	✓	✓
4.4		✓	✓	✓
4.0 到 4.3			✓	✓
3.8 到 3.12			✓	✓	✓	✓

[6]	此驱动程序版本与虚拟线程不兼容。

提示

要了解如何下载 Java Reactive Streams 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Java Reactive Streams驱动程序和MongoDB Server之间的兼容性：

Java Reactive Streams 驱动程序版本	MongoDB 9.0	MongoDB 8.3	MongoDB 8.1 至 8.2	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0
5.12 到 5.13	✓	✓	✓	✓	✓	✓
5.9 到 5.11	⊛	✓	✓	✓	✓	✓
5.8		✓	✓	✓	✓	✓
5.2 到 5.7		⊛	✓	✓	✓	✓
4.10 到 5.1		⊛	⊛	⊛	✓	✓
4.7 到 4.9		⊛	⊛	⊛	⊛	✓
4.0 到 4.6		⊛	⊛	⊛	⊛	⊛
3.11 到 3.12		✗ [7]	✗ [7]	⊛	⊛	⊛

[ 7 ]

( 1, 2 ) 由于身份验证问题，这些驾驶员版本与MongoDB 8.1 或更高版本不兼容。要学习；了解更多信息，请参阅升级驱动程序版本。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。5.9 和 5.11 之间的所有 Java Reactive Streams 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Java Reactive Streams驱动程序，这包括版本 5.12 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用Java Reactive Streams驱动程序版本 5.2 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 5.12 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月之前发布的所有 Java Reactive Streams 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Java兼容性

本节介绍了 Java Reactive Streams 驱动程序的版本与 Java 的版本之间的兼容性。单元格中的对号（✓）表示 Java Reactive Streams 驱动程序版本与 Java 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

从 Java 8 开始，该表仅列出长期支持 (LTS) Java 版本。驱动程序通过 Java 虚拟机 (JVM) 向后兼容性支持所有晚于 Java 8 的版本。

Java Reactive Streams 驱动程序版本	Java 21	Java 17	Java 11	Java 8	Java 7	Java 6
4.11 到 5.13	✓	✓	✓	✓
4.5 到 4.10	✓ [8]	✓	✓	✓
4.4		✓	✓	✓
4.1 到 4.3			✓	✓	✓	✓

[8]	此驱动程序版本与虚拟线程不兼容。

提示

要了解如何下载 Hibernate ORM 的 MongoDB 扩展并创建您的第一个应用程序，请参阅开始使用。

Hibernate 兼容性

适用于 Hibernate ORM 的 MongoDB 扩展需要 Hibernate ORM 6.6 或更早版本。

MongoDB Server 兼容性

MongoDB Extension for Hibernate ORM 需要MongoDB Server 7.0 或更高版本。

Java兼容性

适用于 Hibernate ORM 的MongoDB扩展需要Java 17 或更高版本。

Java驱动程序兼容性

适用于 Hibernate ORM 的 MongoDB 扩展需要 MongoDB Java 驱动程序 5.5 或更高版本。

提示

要了解如何开始使用 Spring Session MongoDB 并创建第一个应用程序，请参阅开始使用。

Spring 生态系统兼容性

Spring Session MongoDB与以下 Spring 产品兼容：

春季会话 4.0 或更高版本
Spring 框架 7.0 或更高版本
Spring Boot 4.0 或更高版本
Spring Data 2025.1 或更高版本

MongoDB Server 兼容性

春季会话MongoDB需要MongoDB Server 4.2 或更高版本。

Java兼容性

春季会话MongoDB需要Java 17 或更高版本。

Java驱动程序兼容性

春季会话MongoDB需要MongoDB Java驱动程序5.6.1 或更高版本。

提示

要了解如何下载 Kotlin 同步驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Kotlin驱动程序和MongoDB Server之间的兼容性：

Kotlin 驱动程序版本	MongoDB 9.0	MongoDB 8.3	MongoDB 8.1 至 8.2	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
5.12 到 5.13	✓	✓	✓	✓	✓	✓	✓	✓	✓
5.9 到 5.11	⊛	✓	✓	✓	✓	✓	✓	✓	✓
5.8		✓	✓	✓	✓	✓	✓	✓	✓
5.2 到 5.7		⊛	✓	✓	✓	✓	✓	✓	✓
4.10 到 5.1		⊛	⊛	⊛	✓	✓	✓	✓	✓

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序在当前支持的 MongoDB 版本上运行，则它也应该与 9.0 兼容，但我们强烈建议您在非生产环境中对其进行测试。部分兼容的驱动程序版本不支持它连接的 MongoDB Server 版本的所有新功能。5.9 和 5.11 之间的所有 Kotlin 同步驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不与 MongoDB 9.0 协同工作，我们建议升级到与其完全兼容（✓）的驱动程序版本。对于 Kotlin 同步驱动程序，这包括版本 5.12 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的 MongoDB 功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您因为当前的 MongoDB Server 版本已达到其生命周期结束 (EOL) 日期而升级驱动程序版本，我们建议使用与您的 MongoDB 版本完全兼容 (✓) 的驱动程序版本。例如，如果您要升级到 MongoDB Server 8.0，则可以使用 Kotlin Sync 驱动程序版本 5.2 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 5.12 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月日之前发布的所有 Kotlin Sync 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Kotlin兼容性

Kotlin驱动程序需要Kotlin 1.8 或更高版本。

提示

要了解如何下载 Kotlin 协程驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Kotlin协程驱动程序和MongoDB Server之间的兼容性：

Kotlin 驱动程序版本	MongoDB 9.0	MongoDB 8.3	MongoDB 8.1 至 8.2	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
5.12 到 5.13	✓	✓	✓	✓	✓	✓	✓	✓	✓
5.9 到 5.11	⊛	✓	✓	✓	✓	✓	✓	✓	✓
5.8		✓	✓	✓	✓	✓	✓	✓	✓
5.2 到 5.7		⊛	✓	✓	✓	✓	✓	✓	✓
4.10 到 5.1		⊛	⊛	⊛	✓	✓	✓	✓	✓

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。5.9 和 5.11 之间的所有 Kotlin 协程驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Kotlin协程驱动程序，这包括版本 5.12 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

If you're upgrading driver versions because your current MongoDB Server version has reached its end-of-life (EOL) date, we recommend using a driver version that is fully compatible (✓) with your MongoDB version. For example, if you're upgrading to MongoDB Server 8.0, you can use Kotlin Coroutine driver version 5.2 or later.

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 5.12 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。截至 8 月 2032 日的所有 Kotlin 协程驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Kotlin兼容性

Kotlin协程驱动程序需要Kotlin 1.8 或更高版本。

提示

要了解如何下载 Node.js 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了 Node.js 驱动程序和 MongoDB Server 之间的兼容性：

Node.js 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
7.6 到 7.7	✓	✓	✓	✓	✓	✓
7.3 到 7.5	⊛	✓	✓	✓	✓	✓	✓
6.9 到 7.2		✓	✓	✓	✓	✓	✓
5.7 到 6.8		⊛	✓	✓	✓	✓	✓
5.0 至 5.6		⊛	⊛	✓	✓	✓	✓
4.8 到 4.17			⊛	✓	✓	✓	✓
4.0 到 4.7			⊛	⊛	✓	✓	✓
3.7 [9]				⊛	✓	✓	✓
3.6				⊛	⊛	✓	✓

[9]	使用 Node.js 驱动程序版本 3.7 时，对于某些功能，您必须将 `useUnifiedTopology` 标志设置为 `true`。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。7.3 和 7.5 之间的所有节点.js 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于节点.js驱动程序，这包括 7.6 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用 Node.js 驱动程序版本 6.9 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 7.6 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 8 月 2032 日之前的所有 Node.js 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Node.js 兼容性

本节介绍了 Node.js 驱动程序版本与 Node.js 版本之间的兼容性。单元格中的对号（√）表示 Node.js 驱动程序版本与 Node.js 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

下表显示了 Node.js 驱动程序和 Node.js 之间的兼容性：

Node.js 驱动程序版本	Node.js v24.x.x	Node.js v22.x.x	Node.js v20.x.x	Node.js v18.x.x	Node.js v16.x.x	Node.js v14.x.x	Node.js v12.x.x	Node.js v10.x.x	Node.js v8.x.x	Node.js v6.x.x	Node.js v4.x.x
7.0 至 7.7 [10]	✓	✓	✓
6.11 至 6.21 [11]		✓	✓	✓	✓
6.0 至 6.10 [11]			✓	✓	✓
5.6.x 至 5.9.x			✓	✓	✓	✓
5.0.0 至 5.5.x				✓	✓	✓
4.x				✓	✓	✓	✓
3.x						✓	✓	✓	✓	✓	✓

[10]	版本 7.x 的节点.js驱动程序需要 Node.js v20.19.0 或更高版本。

[ 11 ]

( 1, 2 ) Node.js驾驶员的 6.x 版本需要 Node.js v16.20.1 或更高版本。

组件兼容性

下表介绍了 Node.js 驱动程序的附加组件版本兼容性。该表使用关注范围 (^)来表示兼容版本。如果单元格为空，则表示驱动程序版本与该组件不兼容。

Node.js 驱动程序版本	bson	bson-ext [12]	@mongodb-js/kerberos	mongodb-client-encryption	@mongodb-js/zstd	@aws-sdk/credential-providers	gcp-metadata	袜子
7.x	^ 7.0.0		^ 7.0.0	^ 7.0.0	^ 7.0.0	^ 3.806.0	^ 7.0.1	^ 2.8.6
6.x	^ 6.0.0		^ 2.0.1	^ 6.0.0	^ 1.1.0
5.x	^ 5.0.0		^1.0.0 或 ^2.0.0	^ 2.3.0	^ 1.0.0
4.x	^ 4.0.0	^ 4.0.0	^1.0.0 或 ^2.0.0	^1.0.0 或 ^2.0.0	^ 1.0.0
3.x	^ 1.0.0	^1.0.0 或 ^2.0.0	^ 1.0.0	^ 1.0.0

[12]	驱动程序版本 5.x 及更新版本不支持 `bson-ext`。使用 `bson` 代替。

提示

要了解如何下载 PHP 库并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了PHP驱动程序和MongoDB Server之间的兼容性：

PHP 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
ext + lib 2.5	✓	✓	✓	✓	✓	✓	✓
ext + lib 2.4	⊛	✓	✓	✓	✓	✓	✓
ext + lib 2.3	⊛	✓	✓	✓	✓	✓	✓
ext + lib 1.20 至 2.2		✓	✓	✓	✓	✓	✓
ext + lib 1.16 至 1.19		⊛	✓	✓	✓	✓	✓
ext + lib 1.15		⊛	⊛	✓	✓	✓	✓

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。2.3 和 2.4 之间的所有PHP库版本都与MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于PHP库，这包括版本 2.5 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

If you're upgrading driver versions because your current MongoDB Server version has reached its end-of-life (EOL) date, we recommend using a driver version that is fully compatible (✓) with your MongoDB version. For example, if you're upgrading to MongoDB Server 8.0, you can use PHP library version 1.20 or later.

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 2.5 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 年 8 月之前发布的所有 PHP 库都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

PHP兼容性

本节介绍了 PHP 库版本与 PHP 版本之间的兼容性。单元格中的对号 (✓)表示 PHP 库版本与 PHP 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

下表显示了PHP驱动程序和PHP之间的兼容性：

PHP 驱动程序版本	PHP 8.5	PHP 8.4	PHP 8.3	PHP 8.2	PHP 8.1	PHP 8.0	PHP 7.4	PHP 7.3	PHP 7.2
ext + lib 2.1 至 2.5	✓	✓	✓	✓	✓
ext + lib 1.21 至 2.0		✓	✓	✓	✓
ext + lib 1.20		✓	✓	✓	✓	✓	✓
ext + lib 1.17 至 1.19		✓	✓	✓	✓	✓	✓
ext + lib 1.16			✓	✓	✓	✓	✓	✓	✓
ext + lib 1.15			✓	✓	✓	✓	✓	✓	✓

注意

32 位环境

我们建议您在 64 位环境中使用PHP驱动程序。在 32 位环境中，驱动程序会从数据库返回 64 位整数（而不是PHP整数）作为MongoDB\BSON\Int64 类的实例。

PHP扩展兼容性

MongoDB PHP驱动程序由两个组件组成：

MongoDB PHP扩展：用于核心驱动程序功能的最小API
MongoDB PHP库：高级API ，包括客户端、数据库和集合对象的抽象，并提供数据库操作方法

要使用PHP驱动程序，必须安装这两个组件。下表显示了每个PHP库版本支持的最低PHP扩展版本：

PHP库版本	最低PHP扩展版本
2.5	2.5
2.4	2.4
2.3	2.3
2.2	2.2
2.1	2.1
2.0	2.0
1.21	1.21
1.20	1.20
1.19	1.19
1.18	1.18
1.17	1.17
1.16	1.15
1.15	1.15
1.14	1.14
1.13	1.12
1.12	1.12
1.11	1.11
1.10	1.10

提示

大多数PHP库版本需要相同的PHP扩展版本，因为新功能包括对两个组件的更新。我们建议您在应用程序中使用相同的库和扩展版本。

要学习；了解有关PHP库及其要求的更多信息，请参阅 Packagist 上的mongodb/mongodb包。

提示

要了解如何下载 Laravel MongoDB 并创建第一个应用程序，请参阅开始使用。

Laravel 兼容性

本节介绍了Laravel集成的版本与Laravel的版本之间的兼容性。单元格中的对号（✓）表示Laravel集成版本与Laravel版本完全兼容。空单元格表示该组合不兼容或未经过测试。

Laravel MongoDB 版本	Laravel 13 .x	Laravel 12 .x	Laravel 11 .x	Laravel 10.x
5.9 到 5.12	✓	✓
5.7 到 5.8	✓	✓	✓	✓
5.2 到 5.6		✓	✓	✓
4.2 到 5.1			✓	✓
4.1				✓
4.0				✓

要查找未维护的 Laravel 集成版本的兼容性信息，请参阅Github上的 Laravel 版本兼容性。

PHP兼容性

本节展示了 Laravel MongoDB Integration 版本与 PHP 版本之间的兼容性。单元格中的复选标记 (✓) 表示 Laravel MongoDB Integration 版本与该 PHP 版本完全兼容。空白单元格表示该组合不兼容或未经测试。

下表显示了 Laravel MongoDB 与 PHP 之间的兼容性：

Laravel MongoDB 版本	PHP 8.5	PHP 8.4	PHP 8.3	PHP 8.2	PHP 8.1
5.9 到 5.11	✓	✓	✓	✓
4.0 到 5.8	✓	✓	✓	✓	✓

PHP驱动程序兼容性

Laravel MongoDB 5.2 或更高版本需要 v1.21 的MongoDB PHP库和MongoDB PHP扩展。

重要

MongoDB PHP扩展 v2.0兼容性

如果将MongoDB PHP扩展升级到 v2.0，则还必须将 Laravel MongoDB升级到 v5.2.1。Laravel MongoDB v5.2.1仍然支持扩展的 v1.x。

提示

要了解如何下载 PyMongo 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了PyMongo和MongoDB Server之间的兼容性：

PyMongo 版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2	MongoDB 4.0
4.18	✓	✓	✓	✓	✓	✓
4.17	⊛	✓	✓	✓	✓	✓	✓
4.14 到 4.16		✓	✓	✓	✓	✓	✓
4.9 到 4.13		✓	✓	✓	✓	✓	✓	✓
4.4 到 4.8		⊛	✓	✓	✓	✓	✓	✓
4.2 到 4.3		⊛	⊛	✓	✓	✓	✓	✓
3.7 到 4.1		⊛	⊛	⊛	✓	✓	✓	✓

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。4.17 和 4.17 之间的所有PyMongo版本都与MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于PyMongo，这包括 4.18 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用PyMongo版本 4.9 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 4.18 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已寿命结束，截至 2029月日。所有 PyMongo 版本截至八月 2032 日将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Python 兼容性

PyMongo 同时支持 CPython 和 PyPy。

当 Python 的一个版本被标记为生命周期结束 (EOL) 时，PyMongo 的下一个次要版本将删除对该版本的支持。该驱动程序为 EOL Python 版本提供以下持续支持：

CPython ：与 EOL CPython 版本兼容的最后一个 PyMongo 小版本获得了为期一年的重大错误修复。
PyPy ：PyMongo 不支持超过 EOL 日期的 PyPy 版本。

Python 3

CPython

本节介绍了 PyMongo 版本与 CPython 版本之间的兼容性。单元格中的对号 ( ✓ ) 表示 PyMongo 版本与 CPython 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

PyMongo 版本	CPython 3.15	CPython 3.14	CPython 3.13	CPython 3.12	CPython 3.11	CPython 3.10 [13]	CPython 3.9	CPython 3.8	CPython 3.7	CPython 3.6	CPython 3.5	CPython 3.4
4.19	✓	✓	✓	✓	✓
4.14 到 4.18		✓	✓	✓	✓	✓	✓
4.11 到 4.13			✓	✓	✓	✓	✓
4.9 到 4.10				✓	✓	✓	✓	✓
4.8				✓	✓	✓	✓	✓
4.5 到 4.7				✓	✓	✓	✓	✓	✓
4.3 到 4.4					✓	✓	✓	✓	✓
4.2						✓	✓	✓	✓
4.1 [14]						✓	✓	✓	✓	✓
4.0						✓	✓	✓	✓	✓
3.13					✓	✓	✓	✓	✓	✓	✓	✓
3.12						✓	✓	✓	✓	✓	✓	✓
3.11							✓	✓	✓	✓	✓	✓
3.10								✓	✓	✓	✓	✓
3.7 到 3.9									✓	✓	✓	✓

PyPy

本节介绍 PyMongo 版本与 PyPy 版本之间的兼容性。单元格中的对号（✓）表示 PyMongo 版本与 PyPy 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

PyMongo 版本	PyPy3.11	PyPy3.10	PyPy3.9	PyPy3.8	PyPy3.7	PyPy3.6	PyPy3.5
4.19
4.16 到 4.18	✓
4.11 到 4.15		✓
4.8 到 4.10		✓	✓
4.5 到 4.7		✓	✓	✓
4.2 到 4.4		✓	✓	✓	✓
4.1 [14]		✓	✓	✓	✓	✓
4.0		✓	✓	✓	✓	✓
3.12		✓	✓	✓	✓	✓	✓
3.11			✓	✓	✓	✓	✓
3.10				✓	✓	✓	✓
3.7 到 3.9					✓	✓	✓

[13]	Python 3.10 及更高版本与 MongoDB 4.0 及更早版本的 TLS/SSL 不兼容。有关更多信息，请参阅 TLS 页面的故障排除部分。

[ 14 ]

( 1, 2 ) PyMongo 4.1 需要Python 3.6.2 或更高版本。

Python 2

PyMongo版本 3.7 到 3.12 与Python 2.7 和 PyPy2.7 兼容。但是，在某些情况下， PyMongo应用程序在Python 2 环境中运行时的行为会有所不同。

以下部分描述了使用PyMongo时Python 2 和Python 3 之间的行为差异。

二进制数据

在所有版本的Python中， PyMongo将 bytes 类的实例编码为具有子类型 0 的二进制数据，这是二进制数据的默认子类型。在Python 3 中， PyMongo将这些值解码为 bytes 类的实例。在Python 2 中，驱动程序将它们解码为具有子类型 0 的 Binary 类的实例。

以下代码示例展示了PyMongo如何解码 bytes 类的实例。选择Python 2或Python 3标签页以查看相应的代码。

from pymongo import MongoClient
client = MongoClient()
client.test.test.insert_one({'binary': b'this is a byte string'})
doc = client.test.test.find_one()
print(doc)

{u'_id': ObjectId('67afb78298f604a28f0247b4'), u'binary': Binary('this is a byte string', 0)}

from pymongo import MongoClient
client = MongoClient()
client.test.test.insert_one({'binary': b'this is a byte string'})
doc = client.test.test.find_one()
print(doc)

{'_id': ObjectId('67afb78298f604a28f0247b4'), 'binary': b'this is a byte string'}

在解码子类型为 0 的JSON二进制值时，驱动程序的行为方式相同。在Python 3 中，它将这些值解码为 bytes 类的实例。在Python 2 中，驱动程序将它们解码为具有子类型 0 的 Binary 类的实例。有关显示差异的代码示例，请参阅扩展JSON页面。

Pickled ObjectIds

如果您在Python 2 中对 ObjectId 进行了 pickle，并想在Python 3 中对其进行 unpickle，则必须将 encoding='latin-1' 作为参数传递给 pickle.loads() 方法。

以下示例展示了如何使用Python 3 对在Python 2 中进行 pickle 的 ObjectId 进行 unpickle：

import pickle
pickle.loads(b'<ObjectId byte stream>', encoding='latin-1')

如果Python 3应用程序使用兼容的序列化协议来 pickle ObjectId，您可以使用Python 2 来取消 pickle。要在Python 3 中指定兼容协议，请为 pickle.dumps() 方法的 protocol 参数传递 0、1 或 2 的值。

以下示例在Python 3 中序列化 ObjectId，然后打印 ObjectId 和生成的 bytes实例：

import pickle
from bson.objectid import ObjectId
oid = ObjectId()
oid_bytes = pickle.dumps(oid, protocol=2)
print("ObjectId: {}".format(oid))
print("ObjectId bytes: {}".format(oid_bytes))

ObjectId: 67af9b1fae9260c0e97eb9eb
ObjectId bytes: b'\x80\x02cbson.objectid\nObjectId\nq\x00...

以下示例取消上一示例中 ObjectId 的封装，然后打印 bytes 和 ObjectId 实例：

import pickle
from bson.objectid import ObjectId
oid_bytes = b'\x80\x02cbson.objectid\nObjectId\nq\x00...'
oid = pickle.loads(oid_bytes)
print("ObjectId bytes: {}".format(oid_bytes))
print("ObjectId: {}".format(oid))

ObjectId bytes: b'\x80\x02cbson.objectid\nObjectId\nq\x00)...
ObjectId: 67af9b1fae9260c0e97eb9eb

提示

要了解如何下载 PyMongoArrow 并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

支持的 MongoDB Server 版本取决于您的 PyMongo 版本。要了解 PyMongo 支持哪些服务器版本，请参阅 PyMongo 兼容性页面上的 MongoDB Server 兼容性。

PyArrow 兼容性

下表列出每个 PyMongoArrow 版本所需的 PyArrow 版本：

PyMongoArrow 版本	PyArrow 版本
1.15.x	25.x
1.14.x	24.x
1.12.x - 1.13.x	23.x
1.11.x	22.x
1.10.x	21.x
1.8.x - 1.9.x	20.x
1.7.x	19.x
1.6.x	18.x
1.5.x	17.x
1.4.X	16.x

Python 兼容性

PyMongoArrow 需要 CPython 3.10、3.11、3.12、3.13 或 3.14。

PyMongo兼容性

PyMongoArrow 需要PyMongo 4.4 或更高版本。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Motor和MongoDB Server之间的兼容性：

Motor 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2	MongoDB 4.0	MongoDB 3.6
3.7	⊛	✓	✓	✓	✓	✓	✓	✓
3.6		✓	✓	✓	✓	✓	✓	✓	✓
3.2 到 3.5		⊛	✓	✓	✓	✓	✓	✓	✓
3.1		⊛	⊛	✓	✓	✓	✓	✓	✓
3.0		⊛	⊛	⊛	✓	✓	✓	✓	✓

Python 兼容性

本节介绍 Motor 版本与 Python 版本之间的兼容性。单元格中的对号（✓）表示 Motor 版本与 Python 版本完全兼容。空单元格表示组合不兼容或未经测试。

下表显示了Motor和Python之间的兼容性：

Motor 驱动程序版本	Python 3.13	Python 3.12	Python 3.11	Python 3.10	Python 3.9	Python 3.8	Python 3.7
3.7	✓	✓	✓	✓	✓
3.6	✓	✓	✓	✓	✓	✓
3.5		✓	✓	✓	✓	✓
3.3 到 3.4		✓	✓	✓	✓	✓	✓
3.1 至 3.2			✓	✓	✓	✓	✓
3.0				✓	✓	✓	✓

注意

异步支持

对于asyncio支持，Motor需要Python 3.4 或更高版本，或者带有 PyPI 的 asyncio包的Python 3.3。

PyMongo兼容性

下表显示了Motor和PyMongo的等效版本：

Motor版本	PyMongo 版本
3.7	4.10
3.6	4.9
3.3	4.4
3.1	4.2
3.0	4.0

提示

要了解如何下载 Django MongoDB 后端并创建第一个应用程序，请参阅开始使用。

PyMongo兼容性

Django MongoDB后端支持PyMongo 4.7 及更高版本。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了 Django MongoDB 后端和 MongoDB Server 之间的兼容性：

Django MongoDB后端版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0
6.1	✓	✓	✓
6.0	✓	✓	✓
5.2	✓	✓	✓	✓

Django 兼容性

Your major and minor version of Django MongoDB Backend must match your Django version. For example, Django MongoDB Backend 6.0 requires Django 6.0.

语言兼容性

本节介绍了 Django MongoDB 后端版本与 Python 版本之间的兼容性。单元格中的对号（√）表示 Django MongoDB 后端版本与 Python 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

下表显示了 Django MongoDB 后端和 Python 之间的兼容性：

Django MongoDB后端版本	Python 3.14	Python 3.13	Python 3.12	Python 3.11	Python 3.10
6.1	✓	✓	✓
6.0	✓	✓	✓
5.2	✓	✓	✓	✓	✓

提示

要了解如何下载 Ruby 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Ruby驱动程序和MongoDB Server之间的兼容性：

Ruby 驱动程序	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
2.26	✓	✓	✓	✓	✓	✓	✗
2.24 到 2.25	⊛	✓	✓	✓	✓	✓	✓
2.21 到 2.23		✓	✓	✓	✓	✓	✓
2.19 到 2.20		⊛	✓	✓	✓	✓	✓
2.18		⊛	⊛	✓	✓	✓	✓
2.16 到 2.17		⊛	⊛	⊛	✓	✓	✓
2.14 到 2.15		⊛	⊛	⊛	⊛	✓	✓
2.13		⊛	⊛	⊛	⊛	✓ [15]	✓
2.12		⊛	⊛	⊛	⊛	⊛	✓
2.11		⊛	⊛	⊛	⊛	⊛	✓ [16]
2.10		⊛	⊛	⊛	⊛	⊛	✓ [17] [16]

[15]	从驱动程序版本2.14开始实施 OCSP 验证。

[17]	从驱动程序版本 2.11 开始，对分片的拓扑结构中的 SRV 记录进行轮询。

[ 16 ]

( 1, 2 ) 从驾驶员版本 2.12 开始实施客户端加密。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。2.24 和 2.25 之间的所有 Ruby 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Ruby驱动程序，这包括版本 2.26 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用Ruby驱动程序版本 2.21 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 2.26 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已寿命结束，截至 2029月日。所有 Ruby 驱动程序发布截至 8 月 2032 日将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Ruby 兼容性

本节介绍 Ruby 驱动程序版本与 Ruby 版本之间的兼容性。单元格中的对号（✓）表示 Ruby 驱动程序版本与 Ruby 版本完全兼容。空白单元格表示组合不兼容或未经过测试。

下表显示了Ruby驱动程序和Ruby之间的兼容性：

Ruby 驱动程序	Ruby 4.0	Ruby 3.3	Ruby 3.2	Ruby 3.1	Ruby 3.0	Ruby 2.7	JRuby 9.4	JRuby 9.3	JRuby 9.2
2.23.0 至 2.26.0	✓	✓	✓	✓	✓		✓	✓
2.21.1 至 2.22.0		✓	✓	✓	✓		✓	✓
2.20 至 2.21.0			✓	✓	✓		✓	✓
2.19			✓	✓	✓	✓		✓	✓

该驱动程序不支持旧版本的Ruby。

Rails/ActiveSupport 兼容性

Ruby驱动程序不依赖于 ActiveSupport。但是，如果您的应用程序使用 ActiveSupport 或 Ruby on Rails，则必须加载驱动程序的 ActiveSupport 兼容性代码才能确保时间序列化等行为正确：

require 'mongo'
require 'mongo/active_support'

使用 Mongoid 7.0.6 或更新版本的应用程序无需显式加载驱动程序的 ActiveSupport 代码，因为 Mongoid 会自动执行此操作。

TLS/SSL 兼容性

Ruby驱动程序使用根本的Ruby openssl 扩展支持的协议。openssl 扩展通常会公开操作系统的 OpenSSL 库中提供的功能。

行业最佳实践和某些法规要求使用 TLS 1.1 或更高版本。某些操作系统或版本可能不提供支持这些 TLS 版本的 OpenSSL 版本。

如果您使用的是 10.13 (High Sierra) 之前的 macOS 版本，则需要从 rvm、homebrew、macports 或其他类似来源安装Ruby 。有关更多选项，请参阅安装Ruby。

如果您使用的是Linux或其他非 macOS Unix 系统，则可以按如下方式检查 OpenSSL 版本：

openssl version

如果版本号早于 1.0.1，不支持TLS 1.1 或更高版本。请联系您的操作系统供应商以获取解决方案或升级到较新的发行版。

您可以通过运行以下命令来检查 TLS 版本：

ruby -e "require 'net/http'; require 'json'; puts JSON.parse(Net::HTTP.get(URI('https://www.howsmyssl.com/a/check')))['tls_version']"

运行该命令后，您必须看到 TLS 1.X，其中 X 大于或等于 1。

要学习；了解有关 TLS 版本及其安全影响的更多信息，请参阅传输层安全速查表。

注意

JRuby 限制

由于 JRuby 的限制，驱动程序不支持 ECDSA 服务器证书或 OCSP 终结点检查。

提示

要了解如何下载 Mongoid 并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

单元格中的对号 ( ✓ ) 表示 Mongoid 版本与 MongoDB Server 版本兼容。空白单元格表示组合不兼容或未经测试。

下表显示了 Mongoid 和MongoDB Server之间的兼容性：

Mongoid 版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
9.0 到 9.1	⊛	✓	✓	✓	✓	✓	✓
8.0 到 8.1			✓	✓	✓	✓	✓

Ruby 兼容性

本节介绍 Mongoid 和 Ruby 各个版本之间的兼容性。单元格中的对号 ( ✓ ) 表示 Mongoid 版本与 Ruby 版本完全兼容。空白单元格表示组合不兼容或未经测试。

Mongoid 版本	Ruby 4.0	Ruby 3.2	Ruby 3.1	Ruby 3.0	Ruby 2.7	Ruby 2.6	JRuby 9.4	JRuby 9.3
9.0 到 9.1	✓ [18]	✓	✓	✓	✓		✓
8.1		✓	✓	✓	✓	✓		✓
8.0			✓	✓	✓	✓		✓

[18]	Mongoid v9.0.11引入对Ruby 4.0 的官方支持。

Ruby驱动程序兼容性

Mongoid 8.0 到 9.0 需要MongoDB Ruby驱动程序2.18 或更高版本。

注意

补丁版本兼容性

同一次要发布中较旧的 Mongoid 补丁版本可能支持较旧的 Ruby 驱动程序版本。示例，Mongoid v7.0.5支持Ruby驱动程序v2.5 及更高版本，但 Mongoid v7.0.6需要驱动程序v2.7 或更高版本。

Ruby on Rails 兼容性

下表显示了 Mongoid 和 Ruby on Rails 之间的兼容性。单元格中的对号（✓）表示 Mongoid 版本与 Rails 版本兼容。空白单元格表示组合不兼容或未经测试。

Mongoid 版本	Rails 8.0	Rails 7.2	Rails 7.1	Rails 7.0	Rails 6.1	Rails 6.0	Rails 5.2
9.0 到 9.1	✓ [19]	✓ [20]	✓ [21]	✓	✓	✓
8.1	✓ [19]	✓ [20]	✓ [21]	✓	✓	✓	✓ [22]
8.0			✓ [21]	✓	✓	✓	✓ [22]

[ 19 ]

( 1, 2 ) Rails 8.0 需要 Mongoid v8.1.7 和 v9.0.3 在各自的 8 .1 和 9.0 稳定分支。

[ 20 ]

( 1, 2 ) Rails 7.2 需要 Mongoid v8.1.6 和 v9.0.2 在各自的 8 .1 和 9.0 稳定分支。

[ 21 ]

( 1, 2, 3 ) Rails 7.1 需要 Mongoid v8.0.7 或 v8.1.3相应的 8.0 和 8.1 稳定分支。

[ 22 ]

( 1, 2 ) 不支持将 Rails 5.x 与Ruby 3 一起使用。

Rails 框架支持

Mongoid 与构成 Ruby on Rails 的许多框架兼容。下表显示 Mongoid 与每个框架的兼容性。勾选标记（✓）表示支持该框架。空单元格表示该框架直接依赖于 Active Record，如果没有它，可能无法按预期方式工作。

提示

要使用直接依赖 Active Record 的框架，请在应用程序中安装 Mongoid 和 Active Record。

Rails 框架	Mongoid 支持	注意
`ActionCable`	✓	`ActionCable` 没有适用于MongoDB适配器，但您可以将任何现有适配器（例如 Redis 适配器）与 Mongoid 模型一起使用。
`ActionMailbox`		直接依赖于 Active Record。
`ActionMailer`	✓
`ActionPack`	✓
`ActionText`		直接依赖于 Active Record。
`ActionView`	✓
`ActiveJob`	✓	将 `BSON::ObjectId` 值序列化为字符串，然后在作业内重新构建它们。要了解更多信息，请参阅 ActiveJob。
`ActiveModel`	✓	`Mongoid::Document` 模块包括 `ActiveModel::Model` 并利用 `ActiveModel::Validations` 进行文档验证。
`ActiveRecord`	✓	Mongoid 是 Active Record 的替代方案。您可以在同一个应用程序中同时运行这两个方案。
`ActiveStorage`		直接依赖于 Active Record。
`ActiveSupport`	✓	`Mongoid` 模块需要 `ActiveSupport`。 `Mongoid` 使用 `ActiveSupport::TimeWithZone` 处理时间值。

提示

要了解如何下载 Rust 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Rust驱动程序和MongoDB Server之间的兼容性：

Rust 驱动程序版本	MongoDB 9.0	MongoDB 8.0	MongoDB 7.0	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
3.9 [23]	✓	✓	✓	✓	✓	✓	⊛
3.6 至 3.8 [23]	⊛	✓	✓	✓	✓	✓	✓
3.1 至 3.5 [23]		✓	✓	✓	✓	✓	✓
2.6 至 3.0 [23]		⊛	✓	✓	✓	✓	✓
2.5 [23]		⊛	⊛	⊛	✓	✓	✓
2.4 [24]		⊛	⊛	⊛	✓	✓	✓
2.2 至 2.3 [25]		⊛	⊛	⊛	✓	✓	✓
2.1 [26]		⊛	⊛	⊛	✓	✓	✓
2.0 [27]		⊛	⊛	⊛	✓	✓	✓

Rust驱动程序与早于 4.2 的MongoDB Server版本不兼容。

[ 23 ]

（1、2、3、4、5）这些Rust驾驶员版本不支持OCSP。

[24]	此 Rust 驱动程序版本不支持 Decimal 128或OCSP。

[25]	这些Rust驱动程序版本不支持Decimal128、客户端字段级加密、GridFS或OCSP。

[26]	此 Rust 驱动程序版本不支持十进制128、客户端字段级加密、 GridFS 、 OCSP或变更流。

[27]	此Rust驱动程序版本不支持Decimal128、客户端字段级加密、GridFS、OCSP、变更流或因果一致性。

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。3.6 和 3.8 之间的所有 Rust 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Rust驱动程序，这包括版本 3.9 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

If you're upgrading driver versions because your current MongoDB Server version has reached its end-of-life (EOL) date, we recommend using a driver version that is fully compatible (✓) with your MongoDB version. For example, if you're upgrading to MongoDB Server 8.0, you can use Rust driver version 3.1 or later.

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 3.9 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。在 2032 月之前发布的所有 Rust 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Rust兼容性

本节介绍了 Rust 驱动程序版本与 Rust 版本之间的兼容性。单元格中的对号 (✓) 表示 Rust 驱动程序版本与 Rust 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

下表列出了每个版本的Rust驱动程序的最低支持Rust版本 (MSRV)：

Rust 驱动程序版本	支持的最低Rust版本
3.7	1.88
3.6	1.85
3.3 至 3.5	1.83
3.2	1.71.1
2.8 到 3.1	1.61.0
2.4 到 2.7	1.57.0

注意

MSRV 更新

Rust驱动程序仅在主要版本和次要版本中更新其 MSRV（最低支持的Rust版本），并且仅更新到已经发布至少六个月的Rust版本。

提示

要了解如何下载 Scala 驱动程序并创建第一个应用程序，请参阅开始使用。

MongoDB Server 兼容性

本节介绍MongoDB Server版本和驱动程序版本之间的兼容性。下表解释了兼容性级别：

Icon	解释
✓	支持所有功能。
⊛	该驱动程序版本将与 MongoDB 版本一起使用，但并不支持所有新的 MongoDB 功能。
✗	该驱动程序版本不适用于 MongoDB 版本。尝试连接到 MongoDB 版本将会导致错误。
无标记	驱动程序版本未使用 MongoDB 版本测试。

下表显示了Scala驱动程序和MongoDB Server之间的兼容性：

Scala 驱动程序版本	MongoDB 9.0	MongoDB 8.3	MongoDB 8.1 至 8.2	MongoDB 8.0	MongoDB 7.0	MongoDB 6.1	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2
5.12 到 5.13	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
5.9 到 5.11	⊛	✓	✓	✓	✓	✓	✓	✓	✓	✓
5.8		✓	✓	✓	✓	✓	✓	✓	✓	✓
5.2 到 5.7		⊛	✓	✓	✓	✓	✓	✓	✓	✓
4.10 到 5.1		⊛	⊛	⊛	✓	✓	✓	✓	✓	✓
4.8 到 4.9		⊛	⊛	⊛	⊛	✓	✓	✓	✓	✓
4.7		⊛	⊛	⊛	⊛	⊛	✓	✓	✓	✓

常见问题解答

我的驱动程序版本与MongoDB 9.0 部分兼容 (⊛)。我的应用程序能运行吗？

如果您的应用程序可在当前支持的MongoDB版本上运行，则它也应可在 9.0 上运行，但我们强烈建议您在非生产环境中进行测试。部分兼容的驱动程序版本并不支持其连接到的MongoDB Server版本的所有新功能。5.9 和 5.11 之间的所有 Scala 驱动程序版本都与 MongoDB Server 9.0 部分兼容。

如果您的应用程序不支持MongoDB 9.0，我们建议升级到与之完全兼容 (✓) 的驱动程序版本。对于Scala驱动程序，这包括版本 5.12 或更高版本。使用完全兼容的驱动程序版本可确保长期稳定性，并允许您的应用程序使用最新的MongoDB功能。

有关每个版本的驱动程序中添加或删除的功能列表，请参阅驱动程序的发布说明。有关每个版本的MongoDB Server添加或删除的功能列表，请参阅MongoDB Server发布说明。

我的驱动程序版本与 7.0 和 8.0 完全兼容，但MongoDB 7.0 已停产。我的升级路径是怎样的？

如果您由于当前的MongoDB Server版本已达到其生命周期结束 (EOL) 日期而要升级驱动程序版本，我们建议您使用与您的MongoDB版本完全兼容 (✓) 的驱动程序版本。示例，如果要升级到MongoDB Server 8.0，则可以使用Scala驱动程序版本 5.2 或更高版本。

但是，如果您要升级到MongoDB Server 9.0，我们建议您升级到驱动程序版本 5.12 或更高版本。这可确保您的应用程序可以使用MongoDB Server 9.0 中提供的所有功能，并提供与未来版本的术语兼容性。

我的驱动程序版本何时达到 EOL？

新的驱动程序版本与过去三年内达到 EOL 的任何MongoDB Server版本完全兼容。在此期限之后，新的驱动程序版本可能与 EOL MongoDB Server版本不完全兼容。

示例，MongoDB Server 8.0 已于 2029 月日停止支持 (EOL)。203220248.0 年 8 月之前的所有 Scala 驱动程序发布都将与 MongoDB Server 8.0 完全兼容。

为了确保长期兼容性和安全性，我们建议您在MongoDB Server版本达到 EOL 之前升级驱动程序。要学习更多有关MongoDB Server发布和 EOL 日期的信息，请参阅MongoDB软件生命周期时间表。

Scala兼容性

本节介绍了 Scala 驱动程序的版本与 Scala 的版本之间的兼容性。单元格中的对号（✓）表示 Scala 驱动程序版本与 Scala 版本完全兼容。空单元格表示该组合不兼容或未经过测试。

Scala 驱动程序版本	Scala 3	Scala 2.13	Scala 2.12	Scala 2.11
5.7 +	✓	✓	✓	✓
2.0 到 5.6		✓	✓	✓