副本集连接字符串必须包含至少两个可连通节点地址并显式指定replicaset参数，否则驱动按单机模式处理；需确保网络互通、tls配置正确、特殊字符url编码，必要时用directconnection=true跳过自动发现。
副本集连接字符串必须包含多个节点地址
只写一个 host:port 的 URI（比如 mongodb://localhost:27017）无法触发副本集发现逻辑，驱动会当作单机模式处理，即使后端确实是副本集。连接时会报 no replica set members found 或直接超时。
- 至少列出两个可连通的副本集成员，例如：
mongodb://node1:27017,node2:27017,node3:27017 - 所有节点必须属于同一副本集（
_id相同），且网络互通、能互相发现 - 不必列全所有节点，但建议列全——某个节点宕机时，驱动仍能通过其余节点完成自动发现和故障转移
- 若用 Docker 或 Kubernetes，注意容器 hostname 和宿主机解析是否一致；常见坑是容器内能 ping 通，但驱动解析失败，此时应改用宿主机 IP 或启用
directconnection=true
replicaset 参数不是可选的
缺少 ?replicaset=xxx 会导致驱动不启用副本集模式，即使节点列表正确，也会拒绝连接或降级为单机行为。
-
replicaset值必须与副本集实际名称完全一致（大小写敏感），可通过rs.conf()._id在 mongosh 中确认 - 参数名不区分大小写（
REPLICASET、replicaSet都行），但值必须原样匹配 - 不要拼错成
replicasetname或replset—— 这类错误不会报明确提示，只会静默失败 - 如果使用
mongodb+srv://格式（如 Atlas），则**不能**加replicaset参数；SRV 记录已隐含该信息
directconnection=true 是调试和受限环境的救命开关
在 Docker Compose、K8s Service 或 NAT 环境中，副本集成员对外暴露的地址（比如 mongodb://mongo-0:27017）可能无法被客户端反向解析或访问，导致驱动发现失败，卡在“trying to discover cluster”阶段。
- 加
&directconnection=true后，驱动跳过自动发现，只连 URI 中显式列出的节点 - 此时必须确保所列节点中至少有一个是当前主节点，否则写操作会失败（
not master错误） - 该选项禁用故障转移能力——主节点挂了，客户端不会自动切到新主，除非你手动重连
- 生产环境慎用；仅用于调试、CI 测试或明确知道拓扑固定且稳定时
SSL/TLS 和 readPreference 要按需显式声明
很多连接失败其实和认证无关，而是 TLS 配置不匹配或读偏好触发了不可达节点。
- 自建副本集启用了 TLS：必须加
&ssl=true，并确保客户端信任证书链；Atlas 默认强制 SSL，省略该参数会直接拒绝连接 - 需要从从节点读取：显式加
&readpreference=secondary，否则默认走primary；若所有 secondary 不可用，请求会失败而非 fallback - 跨地域部署时建议加
&maxStalenessSeconds=90（最小允许值），避免因网络延迟误判从节点“太旧”而剔除 - 密码含特殊字符（
@、/、:等）必须 URL 编码，比如p@ss/w0rd→p%40ss%2Fw0rd
directconnection 和 replicaset 的协同判断逻辑——这三个参数任何一个没对齐，都可能让连接卡在“看起来能连上，但实际不工作”的状态。
