PHP连接MongoDB副本集配置指南

本文详解了PHP连接MongoDB副本集的关键配置要点：必须使用mongodb://协议（而非已废弃的mongo://），URI中需准确指定replicaSet参数（大小写敏感）、至少包含两个节点地址，并显式配置readPreference（如secondaryPreferred）以保障读取高可用；同时强调合理设置connectTimeoutMS和socketTimeoutMS超时参数以应对跨机房网络延迟，最后通过getManager()->getServers()验证副本集拓扑识别是否成功——避免“看似连接成功实则未真正加入副本集”的隐蔽故障，直击生产环境中最易被忽视的连通性与配置一致性痛点。

PHP 连接 MongoDB 副本集必须用 mongodb:// 协议，不能用 mongo://

旧版 mongo 扩展（已废弃）用 mongo://，新版 mongodb 扩展（官方维护）只认 mongodb://。如果写错协议，会直接报 Uncaught InvalidArgumentException: Invalid URI scheme。

正确写法示例：

$uri = 'mongodb://node1:27017,node2:27017,node3:27017/?replicaSet=rs0';

• node1、node2、node3 是副本集各成员的 host（可为域名或 IP）
• replicaSet=rs0 中的 rs0 必须和 MongoDB 实际配置的副本集名称完全一致（大小写敏感）
• 不强制要求列出全部节点，但建议至少写两个，避免单点故障导致连接失败
• URI 中不能带空格或中文，否则解析失败

必须启用 readPreference 显式控制读取行为

副本集默认走主节点读，但 PHP 驱动不会自动 fallback 到从节点——除非你明确告诉它怎么读。否则在主节点不可用时，find() 会直接报 no suitable servers found。

推荐在连接选项中设置：

$options = [
    'replicaSet' => 'rs0',
    'readPreference' => 'secondaryPreferred',
];

• primary：只读主（默认，强一致性，但主挂了就全挂）
• secondaryPreferred：优先读从，主可用时也可读主（平衡可用性与负载）
• nearest：按网络延迟选最近节点（适合多机房部署）
• 该参数必须是字符串，不是常量（如别写 MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED，那是底层驱动用的）

connectTimeoutMS 和 socketTimeoutMS 得调大，尤其跨机房

副本集节点分散在不同网络区域时，DNS 解析、TCP 握手、心跳探测耗时明显增加。默认超时（10s / 30s）容易触发 connection timed out 或 Failed to connect to XXX:27017: Connection refused。

• connectTimeoutMS：建立 TCP 连接的最大等待时间，建议设为 5000~10000（毫秒）
• socketTimeoutMS：单次操作（如查询）的 socket 级超时，建议 30000 起步
• 这两个值要写在 URI 查询参数里，或传入 $options 数组，不能只靠 ini_set('default_socket_timeout', ...)
• 错误写法：mongodb://...?connectTimeoutMS=5（单位是毫秒，5 毫秒显然不够）

验证副本集状态得用 getServerManager() + getServers()

光看 new MongoDB\Client($uri) 不抛异常，并不代表连上了副本集——它可能只连上了其中一个节点，且该节点不认为自己属于目标 replicaSet。

真正检查副本集拓扑是否识别成功：

$client = new MongoDB\Client($uri, $options);
$servers = $client->getManager()->getServers();
foreach ($servers as $server) {
    echo $server->getHost() . ':' . $server->getPort() . ' → ' . $server->getType() . "\n";
}

• 正常输出应包含多个 RSPrimary、RSSecondary 类型节点
• 如果全是 Standalone，说明 replicaSet 参数没生效，或 MongoDB 实例根本没启用副本集模式
• 如果只返回一个节点，可能是 DNS 解析失败、防火墙拦截、或 URI 中节点地址写错了（比如用了 localhost 但副本集成员互相用内网 IP 通信）

副本集配置的细节（比如节点 host 名是否被所有成员正确解析）比代码本身更容易出问题。连通性测试一定要在 PHP 运行环境中真实执行，不能只靠本地 mongosh 验证。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~