必须先确认集群真实版本和featurecompatibilityversion是否均为≥6.0，否则即使mongod进程为7.0，驱动仍按旧协议通信；再验证驱动拓扑类型为"sharded"且连接字符串含directconnection=false等关键参数。
先确认分片集群真实版本和 featureCompatibilityVersion
升级后驱动连不上，第一件事不是改代码，而是确认集群是否真的完成升级。分片集群里 mongos、config server、shard 副本集三者版本必须全部 ≥ 6.0 才能升级到 7.0；任意一个节点卡在 5.0 或更低，mongos 就会拒绝新版驱动的拓扑发现请求，表现为 MongoServerSelectionError 或静默超时。
连接任意 mongos，执行：
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })返回值必须是 "6.0" 或 "7.0"。若仍是 "5.0"，说明升级流程未走完——即使 mongod 进程已是 7.0，featureCompatibilityVersion 不手动升级，驱动仍按旧协议通信，事务、maxCommitTimeMS 等参数会被忽略或报错。
检查驱动是否识别分片拓扑类型
Node.js 和 Java 驱动在连接分片集群时，会主动探测集群类型。如果驱动版本过低（如 Node.js mongodb@4.17）或配置残留（如 useUnifiedTopology: false），它可能把 mongos 当作单节点直连，导致 serverSelectionTimeoutMS 频繁触发，或后续操作找不到 shard key 路由路径。
验证方式：
- Node.js：连接后打印
client.topology?.description?.type，正确值应为"Sharded"，而非"Unknown"或"Standalone" - Java：调用
MongoClient.getClusterDescription().getType()，必须返回ClusterType.SHARDED - PyMongo：
client.topology_description.server_types中应包含多个"Mongos"类型实例
常见坑：mongodb://localhost:27017 这种单地址写法永远无法识别分片拓扑，必须用 mongodb://mongos1:27017,mongos2:27017/?directConnection=false 显式声明多节点。
驱动版本与 Server 7.0 的硬性匹配规则
MongoDB 7.0 移除了对 5.0/6.0 旧 wire protocol 的兼容支持，驱动必须显式适配新协议栈。不满足以下任一组合，connect() 可能成功但后续命令失败（如 findAndModify 报 CommandNotFound）：
- Server 7.0 + Node.js v18.13+ → 必须用
mongodb@6.x或@7.1.0+（@7.0.0有已知认证 handshake bug） - Server 7.0 + Node.js v16 → 不支持，v16 已被 v7 驱动完全弃用
- Server 7.0 + Java 17+ → 必须用
mongo-java-driver@4.13+，4.12及更早不识别maxTransactionLockRequestTimeoutMS等新字段 - PyMongo 用户注意：
pymongo@4.7+才完整支持 7.0 分片事务语义，4.6会静默忽略writeConcern中的w: "majority"设置
执行 npm list mongodb 或 pip show pymongo 确认实际加载版本，别信 package.json 里写的——子依赖（如某个监控 SDK 锁死 mongodb@3.7）才是真凶。
连接字符串里漏掉关键参数等于白连
分片集群不是副本集，驱动不会自动降级行为。以下参数缺一不可：
-
?directConnection=false：强制驱动走 mongos 路由，禁用直连 shard 的 fallback 行为 -
&minPoolSize=5&maxPoolSize=20：7.0+ mongos 对空闲连接回收更激进，不设minPoolSize容易因连接数归零导致首次查询延迟飙升 -
&serverSelectionTimeoutMS=7000：默认 30s 太长，分片拓扑发现失败应快速暴露，而非卡住整个请求链 -
&authMechanism=MONGODB-AWS类认证机制，必须配套安装@aws-sdk/credential-providers（v7 驱动已将其列为 peer dep）
最容易被忽略的是 directConnection=false。很多团队从副本集迁移到分片后，沿用老连接串，驱动误判拓扑类型，后续所有 shardCollection、moveChunk 管理命令都发到错误节点，错误信息却只显示模糊的 NotMaster。
真正麻烦的从来不是“连不上”，而是“连上了但行为不对”——比如事务不生效、聚合路由错乱、写关注被忽略。这些几乎都源于驱动没真正理解你连的是分片集群，而不是它自以为的副本集或单机。验证拓扑类型和连接参数，比重试十次 connect() 更有效。
