ConnectionTimeoutException 多因 MongoDB 驱动未安装、服务未启动或配置错误；需确认 php-mongodb 扩展已加载且版本≥1.19，服务可直连，TP 中 host 用 127.0.0.1 而非 localhost。
ThinkPHP 连接 MongoDB 报 ConnectionTimeoutException 怎么查
不是代码写错了，大概率是驱动没装对、或 MongoDB 服务根本没起来。ThinkPHP 本身不自带 MongoDB 驱动，它依赖 PHP 的 mongodb 扩展（不是已废弃的 mongo），这个扩展必须手动编译安装，且和 PHP 版本强绑定。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php -m | grep mongodb确认扩展是否加载；没输出就说明没装，别急着改 TP 配置 - 检查
phpinfo()页面里mongodb模块的Version和libmongoc版本，低于 1.19 可能连不上 MongoDB 6+（尤其开启 TLS 时） - 用命令行直连验证服务可用性：
mongosh "mongodb://127.0.0.1:27017" --eval "db.runCommand({ping:1})"，失败就先解决 MongoDB 本身 - TP 配置里的
host别写localhost—— 在 Docker 或某些 Linux 环境下会走 IPv6 回环，改成127.0.0.1更稳
ThinkPHP 6.x 使用 MongoDb 门面报 Class not found
这是典型的“以为装了驱动就能直接用”，但 ThinkPHP 官方并不内置 MongoDB 支持，think-mongo 扩展早已停止维护，TP6 默认根本不认识 MongoDb 这个门面。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 不要试图在
config/database.php里加type => 'mongodb'—— TP6 的数据库抽象层压根不支持它 - 如需操作 MongoDB，推荐用原生客户端：先
composer require mongodb/mongodb，再在控制器里$client = new \MongoDB\Client(...) - 若坚持用门面风格，可自己封装一个
MongoDb门面，但注意：它和Db门面完全无关，不能混用查询构造器 - 别碰网上搜到的
think-mongofor TP6 分支 —— 多数未适配新版驱动，insertOne返回值类型都对不上，运行时报错才改就晚了
SSL routines:tls_process_server_certificate:certificate verify failed 怎么绕过又不失控
本地开发连带 TLS 的 MongoDB Atlas 或自建 SSL 实例时常见。不是简单加 ssl=>false 就行 —— PHP 驱动默认校验证书链，关了可能连不上，硬开又报证书错。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 生产环境绝不要设
allowInvalidCertificates=true，这等于关掉 TLS 校验，和裸连无异 - 本地调试可临时加
'tlsAllowInvalidCertificates' => true到连接选项，但必须限定在APP_DEBUG=true下 - 真正解法是把 MongoDB 服务的 CA 证书（或 Atlas 提供的
ca.pem）路径填进配置：'ca_file' => '/path/to/ca.pem' - 注意 Windows 下路径要用正斜杠或双反斜杠，
C:\certs\ca.pem会导致驱动静默失败
TP6 里复用 MongoDB 连接避免每次新建 Client 实例
每次请求都 new 一个 \MongoDB\Client 看似无害，实际会创建新连接池，短连接模式下频繁握手拖慢响应，还可能触发 MongoDB 的连接数限制。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 利用 TP6 的容器绑定，在
app/provider.php里注册单例：use MongoDB\Client;<br>return [<br> Client::class => function () {<br> return new Client('mongodb://127.0.0.1:27017', [], ['typeMap' => ['root' => 'array']]);<br> },<br>]; - 在控制器中通过依赖注入或
app(Client::class)获取，确保全请求生命周期只用一个连接实例 - 别在模型里直接 new —— 模型可能被多次实例化，连接就重复创建
- 如果用了分库分集合逻辑，可在单例基础上封装一个工厂类，按参数返回不同
Database对象，而非不同Client
驱动版本、TLS 配置、连接复用这三块，任意一个没对齐，都会让 MongoDB 在 TP 里表现得“时好时坏”。特别是升级 PHP 或 MongoDB 后，光改代码不查扩展版本，问题只会更隐蔽。
