PHP 8.1+ 下 composer require mongodb/mongodb 仅安装纯 PHP 驱动，不包含原生 C 扩展；必须单独安装并启用 php-mongodb 扩展（如 apt install php-mongodb），否则会报 Class 'MongoDB\Driver\Manager' not found。
PHP 8.1+ 环境下，composer require mongodb/mongodb 能正常安装，但**这不等于 MongoDB 扩展已就绪**——它只是官方的纯 PHP 驱动（ODM 层），底层仍依赖 mongodb 这个原生 PHP 扩展（即 php-mongodb，由 C 编写，必须编译进 PHP）。跳过原生扩展直接跑 mongodb/mongodb 会报 Class 'MongoDB\Driver\Manager' not found。
确认系统是否已启用 mongodb 原生扩展
运行 php -m | grep mongodb。若无输出，说明原生扩展未安装或未启用；若有输出，再执行 php -r "echo extension_loaded('mongodb') ? 'yes' : 'no';" 确认是否被加载。
- Linux（Debian/Ubuntu）：用
sudo apt install php-mongodb安装，然后检查/etc/php/*/cli/conf.d/20-mongodb.ini是否存在且含extension=mongodb.so - Linux（CentOS/RHEL）：需先启用 EPEL 和 Remi 源，再运行
sudo yum install php-pecl-mongodb或sudo dnf install php-pecl-mongodb - macOS（Homebrew + PHP）：执行
pecl install mongodb，然后在php.ini中添加extension="mongodb"（注意不是mongodb.so，M1/M2 上可能是mongodb.so，取决于 PHP 架构） - Windows：从 pecl.php.net 下载对应 PHP 版本、线程安全（TS/NTS）、架构（x64/x86）的
php_mongodb.dll，放入ext/目录，并在php.ini中加extension=php_mongodb.dll
composer require mongodb/mongodb 的实际作用
这个命令只安装官方维护的高级封装库，提供 MongoDB\Client、MongoDB\Collection 等易用类，屏蔽了底层 Manager、Query 等 Driver 层细节。它本身不带任何 C 扩展逻辑，也不修改 php.ini。
- 安装后可直接使用：
$client = new MongoDB\Client('mongodb://127.0.0.1:27017'); $collection = $client->mydb->users; $result = $collection->insertOne(['name' => 'Alice']); - 若你只需要 Driver 层控制（比如自定义序列化、连接池管理），可跳过此包，直接用
MongoDB\Driver\Manager等类（前提是原生扩展已启用） - 该包要求 PHP >= 7.4，且依赖
ext-mongodb >= 1.13.0；旧版 PHP 或低版本原生扩展会触发 Composer 安装失败
常见报错与定位方法
遇到 Class 'MongoDB\Driver\Manager' not found，95% 是原生扩展缺失，和 Composer 无关。别急着重装包，先查扩展。
立即学习“PHP免费学习笔记（深入）”；
-
PHP Fatal error: Uncaught Error: Class 'MongoDB\Client' not found：说明mongodb/mongodb包未被自动加载，检查vendor/autoload.php是否已引入，或运行过composer dump-autoload -
Failed to load /path/to/mongodb.so: undefined symbol: php_json_serializable_ce：原生扩展版本与 PHP 版本不匹配（如用 PHP 8.2 扩展去跑 PHP 8.1），需重新编译或换对应版本的包 -
Could not authenticate user ... against database admin：不是扩展问题，是连接字符串或数据库权限配置错误，检查mongodb://user:pass@host/db?authSource=admin中的authSource是否正确
真正卡住的地方往往不在 Composer 命令本身，而在原生扩展的 ABI 兼容性——比如 Alpine Linux 上用 apk add php81-pecl-mongodb 安装后仍报错，大概率是 musl libc 与预编译 so 的链接问题，此时得用源码编译（pecl install mongodb）并确保 build-base、autoconf、php81-dev 都到位。
