thinkphp8连接mongodb必须同时满足三个条件：安装php官方mongodb扩展、使用composer require topthink/think-mongo适配包、database.php中type=>'mongo'等配置严格匹配；缺一则报class not found错误。

ThinkPHP8 连接 MongoDB 必须同时满足三个条件：PHP 层有官方 mongodb 扩展、项目里装对 ThinkPHP 适配包、配置项严格匹配驱动识别规则。缺一不可，否则直接报 Class 'MongoDB\Client' not found 或 Class 'think\mongo\Connection' not found。

必须安装 PHP 官方 mongodb 扩展

TP8 不自带 MongoDB 驱动，它依赖 PHP 进程加载的 官方 mongodb 扩展（不是已废弃的 mongo 扩展，也不是 Composer 的 mongodb/mongodb 包）。

• Windows：下载与 PHP 版本（如 8.2）、线程安全模式（TS/NTS）、VC 编译器（如 VC17）完全匹配的 php_mongodb.dll，放入 php/ext/ 目录，并在 php.ini 中添加 extension=mongodb
• macOS/Linux：运行 pecl install mongodb，确认 php.ini 已写入 extension="mongodb.so"
• 关键动作：重启 Web 服务器或 PHP-FPM，否则 php -m | grep mongodb 无输出，phpinfo() 也看不到该模块

必须用 composer require topthink/think-mongo

TP8 不兼容官方 mongodb/mongodb 包，只认官方维护的 ThinkPHP 适配层。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 执行：composer require topthink/think-mongo
• 若之前误装过 mongodb/mongodb，先运行 composer remove mongodb/mongodb 再重装
• 装完检查 vendor/topthink/think-mongo/src/Connection.php 是否存在——这是 TP8 能识别 type => 'mongo' 的唯一入口文件

database.php 配置必须精准

TP8 数据库工厂靠 type 字段决定实例化哪个连接类，写错值就跳过整个 MongoDB 驱动层。

• 'type' => 'mongo'（必须是字符串 'mongo'，不能是类名或路径）
• 'hostname' => '127.0.0.1'（不要写 localhost，系统可能解析为 ::1 导致 ECONNREFUSED）
• 'hostport' => 27017（整型更稳妥，避免引号包裹）
• 'database' => 'your_db_name'（数据库名必填）
• 其他如 username、password 按需填写，空字符串可留空

模型中要显式指定连接和集合

即使全局配置了 MongoDB，默认模型仍走 MySQL。必须在模型类中声明才能启用 MongoDB 支持。

• 在模型类顶部添加：protected $connection = 'mongo';
• 指定操作的集合：protected $collection = 'user';（对应 MongoDB 中的 collection 名）
• 不设 $connection，查询时会报错或静默回退到默认数据库

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！