php 8.1+ 安装 mongodb 扩展失败主因是缺少 c 依赖库（如 libmongoc、libbson），非 php 版本问题；ubuntu/debian 用 apt install php-mongodb，centos/rhel 需先装 mongo-c-driver-devel，再通过 git clone + install.sh 编译更可靠。
PHP 8.1+ 安装 mongodb 扩展失败：找不到 mongoc 或 libbson
根本原因不是 PHP 版本不兼容，而是系统缺少 C 依赖库。Ubuntu/Debian 下直接 apt install php-mongodb 通常能成功；但 CentOS/RHEL 或源码编译 PHP 时，pecl install mongodb 会卡在编译阶段，报错类似 error: mongoc/mongoc.h: No such file or directory。
实操建议：
- 先确认是否已安装
libmongoc-1.0-dev和libbson-1.0-dev（Ubuntu/Debian）或mongo-c-driver-devel（CentOS 8+/RHEL 8+） - 用
pkg-config --modversion libmongoc-1.0验证头文件和库路径是否被识别 - 如果用
pecl install mongodb失败，改用git clone https://github.com/mongodb/mongo-php-driver.git && cd mongo-php-driver && git submodule update --init && ./install.sh更可控 - 扩展启用后，检查
php -m | grep mongodb和php --ri mongodb输出是否含mongodb support => enabled
连接字符串里写错 mongodb:// 还是 mongodb+srv://
用错协议会导致连接超时或认证失败，且错误信息非常模糊，比如 Failed to connect to localhost:27017: Connection refused —— 实际可能是 DNS 解析失败，而非端口不通。
实操建议：
- 本地单机部署、Docker 启动的 MongoDB，一律用
mongodb://localhost:27017 - Atlas 或其他云服务（含 SRV 记录），必须用
mongodb+srv://，且不能指定端口；它会自动查 DNS 获取真实地址和 TLS 设置 -
mongodb+srv://连接默认强制开启 TLS，若本地测试想关 TLS，得加选项：mongodb+srv://user:pass@cluster/?tls=false（仅限开发环境） - 密码里含特殊字符（如
@、/）必须 URL 编码，否则解析器截断连接串 —— 用rawurlencode()处理密码再拼接
MongoDB\Driver\Manager vs MongoDB\Client：该用哪个
前者是底层驱动，后者是官方推荐的高级封装。新手直接用 MongoDB\Client 即可，除非你要精细控制连接池、自定义序列化或绕过 ODM 做极致性能优化。
实操建议：
- 绝大多数 CRUD 场景用
MongoDB\Client，它自动管理Manager和会话，代码更直白 -
MongoDB\Driver\Manager不提供insertOne()这类方法，只能发原始命令（executeCommand()）或写入文档（executeBulkWrite()），需手动处理 BSON 编码 - 使用
MongoDB\Client时，连接字符串里的数据库名（如mongodb://l:27017/mydb）仅作默认上下文，不影响实际操作的库——真正生效的是你调用$client->selectDatabase('otherdb')的地方 - 别在循环里反复 new
MongoDB\Client，它本身是线程安全且带连接池；全局复用一个实例即可
写入后查不到？注意 writeConcern 和 readPreference 默认行为
尤其在副本集或分片集群下，刚 insertOne() 完立刻 findOne()，可能读到旧数据或空结果，不是代码 bug，而是读写分离策略导致的最终一致性窗口。
实操建议：
- 开发调试时，在连接字符串末尾加
&w=majority&readPreference=primary强制主节点读写，避免“写完看不到” - 生产环境慎用
w=majority，它会拖慢写入速度；更合理的是按业务分级：日志类用w=1，订单类用w=majority -
findOne()查不到，先用countDocuments()确认是否真没写入；如果 count 有值但 find 没返回，大概率是readPreference被设成了secondary且从节点延迟高 - 时间戳字段（如
created_at）别用new \DateTime()直接存，MongoDB 期望MongoDB\BSON\UTCDateTime；否则可能存成字符串，导致范围查询失效
connection timeout 或 cursor not found 错误反向调参。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
