timeouterror 是连接阶段卡死，非查询超时；应调 connecttimeoutms（控制tcp握手超时）和 serverselectiontimeoutms（控制节点选择超时），二者需配合设置，且须整数传入、初始化时指定，uri中需防srv覆盖。
TimeoutError 是连接阶段卡死，不是查询超时
Python 连接 MongoDB 报 TimeoutError（比如 Connection refused 或 timed out），大概率发生在 建立 TCP 连接的最初几秒，而不是执行 find() 或 insert_one() 时。这时候改 socketTimeoutMS 或 maxTimeMS 完全无效——它们管的是连接建立后的读写和操作耗时。
真正该调的是 connectTimeoutMS，它控制客户端尝试与 MongoDB 服务器完成三次握手的最大等待时间，默认值通常是 20000（20 秒）。但很多本地开发环境或容器网络不稳定时，20 秒仍不够，或者你其实想更快失败以便重试/报错。
- 这个参数只在
MongoClient初始化时生效，不能运行时修改 - 必须显式传入，不写就用默认值；写成字符串（如
"5000"）会静默忽略，必须是整数 - 设得太小（比如
100）可能导致偶发性连接失败，尤其跨网络或 TLS 握手慢时
connectTimeoutMS 要和 serverSelectionTimeoutMS 配合用
如果你用的是副本集或分片集群，connectTimeoutMS 只管“连上某一个节点”，而 serverSelectionTimeoutMS 控制“在多个候选节点中选出可用主节点”的总耗时。后者默认 30000（30 秒），常比前者还长。
单独调大 connectTimeoutMS 却不碰 serverSelectionTimeoutMS，可能让你以为连上了，实际还在轮询节点列表、反复尝试连接不可达的 secondary。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 典型组合：把两者都设为相同值，比如
connectTimeoutMS=5000, serverSelectionTimeoutMS=5000 - 如果 MongoDB 地址用了 DNS 名（如
mongodb://mydb.example.com:27017），DNS 解析失败也会被算进serverSelectionTimeoutMS，不是connectTimeoutMS - 使用
directConnection=True可跳过服务发现逻辑，此时serverSelectionTimeoutMS不起作用
常见错误写法和调试建议
很多人把超时参数塞进 URI 字符串，却忽略了 URL 编码和类型转换问题。例如：
mongodb://localhost:27017/?connectTimeoutMS=5000&socketTimeoutMS=30000
这看似正确，但 PyMongo 4.0+ 默认启用 srvServiceName 自动探测，若 DNS 中有 SRV 记录，它会覆盖 URI 中的端口和超时参数——导致设置完全失效。
- 强制禁用 SRV 解析：
MongoClient("mongodb://...", srv=False) - 检查是否真的生效：创建 client 后打印
client.options.pool_options.connect_timeout_ms - 遇到
ServerSelectionTimeoutError而不是TimeoutError？说明问题出在服务发现环节，优先查serverSelectionTimeoutMS和 DNS 配置 - Windows 上启用了防火墙或 WSL2 网络桥接异常时，哪怕
telnet localhost 27017通，PyMongo 仍可能因 IPv6 fallback 卡住——加host="127.0.0.1"强制 IPv4
生产环境别只靠调参，得看根本原因
connectTimeoutMS 是兜底手段，不是根治方案。如果线上频繁触发，大概率是基础设施问题：
- MongoDB 进程没起来，或 bindIp 配置没包含客户端 IP（尤其是 Docker 容器里只绑了
127.0.0.1） - K8s Service 的 endpoints 没同步，或者 headless service 的 DNS 解析返回了已销毁的 Pod IP
- 云厂商安全组放行了端口，但子网 ACL 或主机 iptables 拦截了连接
临时调高超时值能掩盖问题，但会让故障感知延迟更久；调低又容易误伤正常连接。最稳妥的做法是：监控 connection pool size 和 is_primary 状态，在连接失败时记录完整 traceback + 当前 client.nodes 列表，才能定位到底是网络断了、DNS 慢了，还是 MongoDB 自己挂了。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
