MongoDB作为流行的文档型数据库，在PHP项目中的使用频率一直不低。不过不少人在搭建环境时会被PHP官方的驱动体系绕晕：数据库明明装好了，PHP代码里却连不上，或者直接抛出Class 'MongoDB\Client' not found这样的错误。这类问题的根源几乎都指向同一个地方——mongodb扩展没有正确安装或者没有加载。这篇文章把Windows和Linux两种环境下的安装流程完整梳理一遍，顺带讲清楚扩展和库的区别，让你一次把环境配好。
先弄清楚mongodb扩展和mongodb库的关系
PHP操作MongoDB需要两个东西配合工作，一个是扩展，一个是库。扩展的名字叫mongodb，用C语言编写，编译成动态链接文件后由PHP进程加载，负责与MongoDB服务器建立连接、收发协议报文这些底层工作。它本身并不提供面向对象的友好API，直接用它写代码相当繁琐。
日常开发中使用的MongoDB\Client、MongoDB\Collection这些类，其实来自一个叫mongodb/mongodb的composer包，也就是所谓的库。库建立在扩展之上，把底层函数封装成直观的对象接口。所以完整的安装链路是：先装扩展，再用composer装库，两者缺一不可。只装库不装扩展，运行时会报MongoDB PHP extension未安装的错误；只装扩展不装库，代码里就找不到Client类。
另外要提醒一点，老版本的mongo扩展（注意没有结尾的db字母）早已废弃，网上一些年代久远的教程还在教人装mongo扩展，照着做只会浪费时间。现在的标准方案就是mongodb扩展配合mongodb/mongodb库。
Linux环境下安装mongodb扩展
Linux下最省事的方式是pecl一键安装。pecl是PHP官方的扩展仓库工具，装PHP时一般自带。执行下面的命令，它会自动下载源码、编译并完成安装：
pecl install mongodb
如果服务器上没有pecl，或者 pecl 安装时报缺少依赖，可以改用源码手动编译。先确保系统里装好了编译工具链和PHP开发头文件，然后按下面的流程走：
# 安装编译依赖（以CentOS为例） yum install -y gcc php-devel openssl-devel # 下载扩展源码并解压 wget https://pecl.php.net/get/mongodb tar -zxvf mongodb cd mongodb-*/ # 生成configure脚本并编译安装 phpize ./configure --with-php-config=/usr/local/php/bin/php-config make && make install
编译结束后终端会提示扩展文件mongodb.so的存放路径，通常是/usr/local/php/lib/php/extensions/no-debug-non-zts-xxxxx/这样的目录。接着编辑php.ini文件，在扩展配置区域加一行，然后重启PHP服务即可：
extension=mongodb.so
使用apt或yum安装的PHP，php.ini一般位于/etc/php.ini或/etc/php/版本号/apache2/php.ini，根据实际的运行环境找准文件再改，改错了文件等于白忙一场。
Windows环境下安装mongodb扩展
Windows下没有编译环境的话，直接下载官方提供的dll文件最方便。打开PECL网站上的mongodb扩展页面，找到与你的PHP版本号、架构（x64或x86）、线程安全属性完全对应的dll。这里最容易踩坑：线程安全版本对应php_mongodb.dll，非线程安全版本对应php_mongodb_nts.dll，下载错了PHP根本加载不了。
怎么判断自己需要哪个版本？查看phpinfo页面顶部的Thread Safety一栏，显示enabled就选线程安全版，显示disabled就选非线程安全版。Architecture一栏则告诉你该下x64还是x86的包。三个信息都对上号再下载，能省去大量排查时间。
下载完成后把dll文件放进PHP安装目录下的ext文件夹，比如C:\php\ext\php_mongodb.dll，然后打开php.ini添加配置并重启Web服务器：
extension=php_mongodb.dll
也可以写完整路径extension=C:\php\ext\php_mongodb.dll，两种写法效果一样，只要确保文件确实在那个位置。修改后记得重启Apache或者IIS，php.ini的改动必须重启才能生效。
验证安装并测试数据库连接
扩展装好后先验证是否加载成功。命令行执行php -m查看已加载模块列表，或者建一个phpinfo页面搜索mongodb关键字：
php -m | grep mongodb
能看到mongodb字样说明扩展已经生效。接下来用composer安装官方库，在项目目录执行：
composer require mongodb/mongodb
最后写一段测试代码，向数据库插入一条文档再查出来，跑通整个链路：
<?php
require 'vendor/autoload.php';
// 创建客户端，默认连接本机27017端口
$client = new MongoDB\Client("mongodb://localhost:27017");
// 选择数据库和集合
$collection = $client->demo->users;
// 插入一条文档
$result = $collection->insertOne([
'name' => '张三',
'age' => 28,
'email' => 'zhangsan@ipipp.com'
]);
echo '插入的文档ID：' . $result->getInsertedId() . PHP_EOL;
// 按条件查询文档
$user = $collection->findOne(['name' => '张三']);
print_r($user);
页面能正常输出文档ID和查询结果，说明扩展、库、数据库三者的衔接全部正常，环境搭建到此完成。
常见安装问题排查
第一个高频问题是扩展与PHP版本不匹配。mongodb扩展的新版本对PHP最低版本有要求，比如某些版本要求PHP不低于7.2，拿老PHP去装新扩展，编译阶段就会失败。装之前先确认php -v的输出，再对照扩展的版本说明选择合适的发布版。
第二个常见问题是修改了php.ini却不生效。这种情况多半是改错了文件，系统里可能同时存在CLI和FPM两套php.ini，命令行和网页用的是不同配置。用php --ini查看命令行实际加载的文件路径，网页端则看phpinfo页面顶部的Loaded Configuration File，两边都确认一遍。
还有一个容易被忽视的点是Linux编译时报openssl相关错误。mongodb扩展依赖OpenSSL库做加密通信，编译前记得装好openssl-devel（Debian系对应libssl-dev），否则configure阶段就会卡住。遇到报错不要急着换教程，先仔细读一遍终端输出的错误信息，绝大多数问题都能从中找到答案。
整体来看，mongodb扩展的安装并不复杂，关键在于理清扩展与库的分工、选对与运行环境匹配的版本，再按照平台对应的方式完成配置。把这几步做扎实，PHP与MongoDB的协作就能稳定跑起来，后续的业务开发也就有了可靠的基础。
MongoDB扩展安装PHP驱动程序MongoDB PHP修改时间：2026-10-05 22:10:27