PHP8项目连MongoDB失败，需四步排查：①确认php -m | grep mongodb有输出，否则安装匹配的php_mongodb.dll或mongodb.so并重启服务；②composer require topthink/think-mongo（非mongodb/mongodb）；③database.php中type必须为'mongo'、hostname必须为'127.0.0.1'；④验证mongod服务确已运行且mongosh ping成功。
PHP8项目中无法连接MongoDB，代码报错Class 'MongoDB\Client' not found或MongoServerSelectionError: connect ECONNREFUSED ::1:27017，说明底层驱动未就绪或连接路径被系统解析机制阻断。
确认PHP已加载官方mongodb扩展
TP8或原生PHP8调用MongoDB的前提是PHP进程能识别MongoDB\Client类，而该类由PHP官方扩展提供，不是Composer包。
执行命令：php -m | grep mongodb
若无任何输出，说明扩展未启用。Windows用户需下载与PHP版本（如8.2）、线程安全模式（TS/NTS）、VC编译器（VC17）完全匹配的php_mongodb.dll，放入ext目录，并在php.ini中添加extension=mongodb；Mac/Linux用户用pecl install mongodb后，检查php.ini是否已自动写入extension="mongodb.so"。
立即学习“PHP免费学习笔记（深入）”；
【必须重启Web服务器或PHP-FPM】，否则phpinfo()中仍不显示mongodb模块，后续所有配置都无效。
用composer装对ThinkPHP8适配包
TP8不直接兼容官方mongodb/mongodb包，它依赖topthink/think-mongo作为数据库类型桥接层。
方法一：执行composer require topthink/think-mongo（推荐）
方法二：若已误装mongodb/mongodb，先运行composer remove mongodb/mongodb，再执行方法一
装完后检查vendor/topthink/think-mongo/src/Connection.php是否存在——这是TP8识别type='mongo'配置的唯一入口文件，缺则报Class 'think\mongo\Connection' not found。
修正database.php连接配置
第一步：打开config/database.php，定位到connections数组
第二步：确保'mongo'连接块中type字段严格等于字符串'mongo'，不可为'\MongoDB\Client'或'mongodb'等其他值
第三步：hostname必须设为'127.0.0.1'，禁止使用'localhost'——后者在PHP8某些环境下会强制解析为IPv6地址::1，而mongod默认只监听127.0.0.1
第四步：完整配置示例如下：
return [
'connections' => [
'mongo' => [
'type' => 'mongo',
'hostname' => '127.0.0.1',
'hostport' => '27017',
'database' => 'myapp',
'username' => '',
'password' => '',
'options' => ['connectTimeoutMS' => 5000],
],
],
];
验证MongoDB服务真实运行状态
即使你认为服务开着，也要用系统级命令交叉验证。
Linux执行：sudo systemctl status mongod → 看Active行是否为active (running)
macOS（Homebrew安装）执行：brew services list | grep mongodb → 状态列必须为started
Windows执行：services.msc → 找到MongoDB Server → 状态必须为“正在运行”
若服务未运行，Linux用sudo systemctl start mongod，macOS用brew services start mongodb-community，Windows在服务管理器中右键启动。
启动后立即测试：mongosh --eval "db.runCommand({ping:1})" → 返回{ ok: 1 }才表示服务响应正常。
模型中正确使用MongoDB集合
TP8模型不能直接new \MongoDB\Client，也不能用$db->users这种魔术属性访问集合。
方法一（推荐）：在模型类中定义$connection = 'mongo'和$collection = 'users'
方法二（手动指定）：在控制器中使用Db::connect('mongo')->name('users')->insert([...])
方法三（原生驱动）：若绕过TP8封装，必须用$client->selectDatabase('myapp')->selectCollection('users')->insertOne([...])，否则报Fatal error: Call to undefined method MongoDB\Database::insertOne()
