phpEnv 默认不带 MongoDB 扩展，因其仅为 PHP 版本管理工具，不自动构建 PECL 扩展；mongodb 扩展需手动通过 pecl install mongodb 编译安装，并配置 php.ini 启用。
phpEnv 本身不提供 MongoDB 服务，也不能自动安装或配置 MongoDB PHP 扩展 —— 它只管理 PHP 版本和基础扩展（如 pdo、curl），而 mongodb 扩展必须手动编译启用。
为什么 phpEnv 默认不带 mongodb 扩展
phpEnv 是一个轻量级的 PHP 多版本切换工具（类似 pyenv），它通过编译安装不同 PHP 版本，但不会自动拉取或构建第三方 PECL 扩展。MongoDB 扩展（mongodb）属于 PECL 包，依赖系统级编译工具链和 libmongoc / libbson 库，phpEnv 不介入这一层。
- 你运行
php -m | grep mongodb返回空，不是 phpEnv 漏装，而是根本没装这个扩展 - 即使你用 phpEnv 切换到 PHP 8.2，
pecl install mongodb仍需手动执行，且可能失败（缺phpize、autoconf或 OpenSSL 头文件） - Windows 下 phpEnv（如某些 fork 版）更难支持，因 PECL 编译在 Windows 上基本不可行，只能靠预编译的
php_mongodb.dll
在 phpEnv 环境下手动启用 mongodb 扩展
假设你已用 phpEnv 安装了 PHP 8.1（路径为 ~/.phpenv/versions/8.1.28），要让它支持 MongoDB：
- 先确认
phpize可用：~/.phpenv/versions/8.1.28/bin/phpize --version；若报错，需装php-dev（Ubuntu/Debian）或php-devel（CentOS/RHEL） - 运行：
pecl install mongodb—— 注意：该命令会调用当前 shell 中的phpize，所以务必先phpenv shell 8.1.28切换版本 - 安装成功后，它会告诉你
.so文件路径，例如：/home/user/.phpenv/versions/8.1.28/lib/php/extensions/no-debug-non-zts-20210902/mongodb.so - 编辑该 PHP 版本专属的
php.ini：~/.phpenv/versions/8.1.28/etc/php.ini，添加一行：extension=/home/user/.phpenv/versions/8.1.28/lib/php/extensions/no-debug-non-zts-20210902/mongodb.so - 验证：
~/.phpenv/versions/8.1.28/bin/php -m | grep mongodb应输出mongodb
连接时常见错误及绕过方式
即使扩展加载成功，MongoDB\Client 实例化仍可能失败，典型报错包括：
立即学习“PHP免费学习笔记（深入）”；
-
PHP Fatal error: Uncaught MongoDB\Driver\Exception\ConnectionTimeoutException: No suitable servers found→ MongoDB 服务根本没运行，或连接字符串写错（比如用了mongodb://127.0.0.1:27017但 mongod 监听的是localhost，IPv6/hosts 解析问题） -
SSL routines:ssl_choose_client_version:unsupported protocol→ PHP 的 OpenSSL 版本太低，无法协商 TLS 1.2+；此时要么升级 PHP（带新版 OpenSSL），要么在连接串加?tls=false（仅限开发环境） -
Class 'MongoDB\Client' not found→ 你用了 Composer 安装的mongodb/mongodb包，但没引入 autoloader；注意：PECL 扩展（mongodb.so）和 Composer 包是两套东西，前者提供底层驱动，后者提供高级 ODM 接口，二者需共存
Windows 下 phpEnv 用户的实际路径处理
Windows 上多数 phpEnv 替代方案（如 phpenv-win）不支持 PECL 编译。你只能：
- 去 PECL 官方 Windows 构建页 下载对应 PHP 版本和线程安全（TS/NTS）、架构（x64/x86）的
php_mongodb.dll - 把它放进 phpEnv 管理的 PHP 版本的
ext/目录（如C:\phpenv\versions\8.1.28\ext\） - 编辑该版本的
php.ini，添加：extension=php_mongodb.dll（注意不是extension=mongodb） - 重启 CLI 或 Web 服务 —— Windows 下 php-fpm 通常不被 phpEnv 管理，得手动启停
真正麻烦的从来不是“怎么加一行配置”，而是确保 phpize 能调通、libmongoc 链接正确、TLS 协议匹配、以及 Windows 下 DLL 依赖不缺失 —— 这些细节一漏，MongoDB\Client 就永远 new 不出来。
