TP8连MongoDB需三步：装PHP官方mongodb扩展、用composer require topthink/think-mongo、配置type='mongo'并设模型$connection和$collection。缺一即报Class not found或查空。
TP8 连 MongoDB 不是改个配置就能用，必须装对扩展、配对驱动、写对模型——漏一步，Class 'think\mongo\Connection' 或 Class 'MongoDB\Client' 找不到就直接报错。
确认 PHP 环境已装官方 mongodb 扩展
TP8 本身不带 MongoDB 驱动，它依赖底层 PHP 的 mongodb 扩展（不是废弃的 mongo）。没这个扩展，任何 TP8 MongoDB 包都会失败。
- 运行
php -m | grep mongodb，有输出才表示扩展已加载 - Windows 用户注意：必须下载与 PHP 版本、TS/NTS、VC 编译器完全匹配的
php_mongodb.dll，放进ext/并在php.ini加extension=mongodb - Mac/Linux 用 Homebrew 或 PECL 安装后，记得重启 PHP-FPM 或 Apache/Nginx，否则
phpinfo()里也看不到 - 常见错误：
Class 'MongoDB\Client' not found—— 八成是这步没走通，别急着配 TP8
用 composer require topthink/think-mongo 而非 mongodb/mongodb
TP8 要的是 ThinkPHP 官方适配层，不是 MongoDB 官方驱动包。装错包会导致模型无法识别连接类型或方法缺失。
- 执行：
composer require topthink/think-mongo（注意不是mongodb/mongodb） - 该包提供
\think\mongo\Connection和\think\mongo\Query，是 TP8 能识别的 MongoDB 封装 - 如果已误装
mongodb/mongodb，先composer remove mongodb/mongodb再重装topthink/think-mongo - 装完检查
vendor/topthink/think-mongo/src/Connection.php是否存在，这是驱动入口
database.php 中 type 必须设为 'mongo'，且不能混用原生 Client
TP8 的数据库连接工厂靠 type 字段决定实例化哪个连接类。设成 'type' => 'mongo' 才会调用 think-mongo 提供的 Connection；设成其他值（比如 'type' => '\MongoDB\Client'）会直接跳过驱动层。
立即学习“PHP免费学习笔记（深入）”；
- 正确配置示例（
config/database.php）：
return [
'connections' => [
'mongo' => [
'type' => 'mongo',
'hostname' => '127.0.0.1',
'hostport' => '27017',
'database' => 'myapp',
'username' => '',
'password' => '',
'options' => ['connectTimeoutMS' => 5000],
],
],
];
- 不要在模型里手动 new
MongoDB\Client再塞进模型属性——这样绕过了 TP8 查询构造器和事件机制，where()、save()等方法全失效 - 不要把
retryWrites=true写进hostname字段，它属于连接 URI 参数，think-mongo不解析这个；如需启用，得在options里传['retryWrites' => true]（仅限较新版本支持）
模型中必须声明 $connection = 'mongo' 且指定 $collection
TP8 不会自动把 Model 映射到 MongoDB，必须显式绑定连接名和集合名，否则默认走 MySQL 连接，查出来是空数组或报错。
- 模型代码示例（
app/model/User.php）：
namespace app\model;
use think\Model;
class User extends Model
{
protected $connection = 'mongo';
protected $collection = 'users'; // 注意：不是 table，是 collection
}
-
$collection是必需的，TP8 的think-mongo驱动靠它定位文档集合；漏掉会查user（默认表名）而不是你想要的users - 不要用
protected $table = 'users'—— MongoDB 没有 table 概念，这个字段会被忽略 - 查询时用
where()没问题，但操作符要符合 MongoDB 语法，比如where('age', '>', 18)可用，但whereRaw()里的 JSON 字符串必须是 PHP 数组格式，不是 JSON 字符串
真正容易被忽略的是：TP8 的 think-mongo 对聚合管道（aggregate）、事务、GridFS 等高级功能支持有限，需要直连 MongoDB\Client 时，务必隔离使用场景——别把它和模型混在一起用，否则连接池、异常捕获、日志跟踪全乱套。
