PHP 8.1+ 连接 MongoDB 必须同时满足三条件：安装官方 mongodb 扩展（非废弃 mongo）、连接字符串含 ?retryWrites=true、MongoDB 服务运行；否则 Client 实例化不报错但写操作静默失败。
PHP 8.1+（含 8.2、8.3、8.4）部署 MongoDB 不是“装个扩展就行”，而是必须同时满足三件事：正确安装 mongodb 扩展（非废弃的 mongo）、启用 ?retryWrites=true 连接参数、且 MongoDB 服务本身在运行——缺一不可，否则 MongoDB\Client 实例化不报错，但 insertOne() 或 find() 会静默失败或抛出模糊异常。
确认 mongodb 扩展已加载，不是 mongo 扩展
PHP 7.0 起官方彻底废弃 mongo 扩展，所有新项目必须用 mongodb（由 mongo-php-driver 提供）。常见错误现象：
-
Class 'MongoDB\Client' not found→ 扩展根本没装或没启用 -
Class 'MongoClient' not found→ 误装了旧版mongo扩展 -
php -m | grep mongo输出为空或只显示mongo→ 立即停手排查
实操验证方式：
- Linux/macOS：
php -r "var_dump(extension_loaded('mongodb'));"必须返回bool(true) - Windows：打开
phpinfo()页面，搜索mongodb，确认模块名、版本、support显示enabled - 若失败：Ubuntu/Debian 直接
sudo apt install php-mongodb；CentOS/RHEL 先sudo yum install mongo-c-driver-devel，再pecl install mongodb；Windows 必须从 PECL 官方 DLL 页面 下载匹配 PHP 版本、TS/NTS、x64/x86 的php_mongodb.dll
连接字符串必须带 ?retryWrites=true
PHP 8.1+ 驱动默认要求写入重试机制，漏掉 ?retryWrites=true 会导致连接看似成功，但所有写操作（insertOne、updateOne）实际被忽略，且无明确报错。
立即学习“PHP免费学习笔记（深入）”；
正确写法示例：
- 本地单机无认证：
mongodb://localhost:27017/?retryWrites=true - 带用户名密码：
mongodb://user:pass@localhost:27017/mydb?retryWrites=true（注意：密码含@、/、:时，必须先用rawurlencode()处理） - 连 MongoDB Atlas：
mongodb+srv://user:pass@cluster.mongodb.net/?ssl=true&tls=true&retryWrites=true&w=majority（&是 HTML 实体，代码中写&）
错误写法：
-
mongodb://localhost:27017（缺少参数，写操作静默失败） -
mongodb://127.0.0.1:27017/?retryWrites=true（IPv4 地址可能因 hosts 解析或 MongoDB 绑定配置导致连接超时，优先用localhost） -
mongodb+srv://...用于本地单机（协议不匹配，DNS 解析失败，报错极模糊）
find() 返回游标，不是数组，不遍历/不 toArray() 就看不到数据
$collection->find([]) 返回的是 MongoDB\Driver\Cursor 对象，这是惰性执行机制：网络连接、查询发起、错误抛出，全部延迟到你真正读取时才发生。直接 var_dump() 只能看到对象结构，不是文档内容。
正确处理方式：
- 小结果集（如配置表、用户列表）：
$cursor->toArray() - 大数据量或流式处理（避免内存溢出）：
foreach ($cursor as $doc) { echo $doc['name']; } - 限制条数：
$collection->find([], ['limit' => 10])，不要用array_slice($cursor->toArray(), 0, 10)
典型坑：
- 调试时只写
var_dump($collection->find(['status' => 'active']));→ 控制台输出object(MongoDB\Driver\Cursor)#5，误以为没查到数据 - 在长生命周期脚本（如 Swoole Worker）里每次请求都
new MongoDB\Client→ 连接池未复用，资源泄漏
插入时 _id 必须是 ObjectId，不能是字符串
手动指定 _id 为字符串（如 '_id' => 'abc123'）虽能存入，但后续用 ObjectId('abc123') 查询将完全匹配不到——因为 MongoDB 内部把字符串 _id 和 ObjectId 当作不同类型处理。
安全做法：
- 让驱动自动生成：
$collection->insertOne(['name' => 'Alice'])→ 返回的InsertOneResult中getInsertedId()是ObjectId实例 - 手动构造 ID：
$collection->insertOne(['_id' => new MongoDB\BSON\ObjectId(), 'name' => 'Bob']) - 查询时也必须用
ObjectId：$collection->findOne(['_id' => new MongoDB\BSON\ObjectId('...')])
容易被忽略的点：很多教程示例省略了 use MongoDB\BSON\ObjectId 声明，实际代码中必须显式引入，否则报 Class 'ObjectId' not found。
