MongoDB本地服务需手动创建数据目录并指定路径启动，前台运行且需验证连接；Java驱动须用4.x+新版，通过MongoClients.create配置超时等参数，注意系统防火墙和IPv6兼容性。
确认 MongoDB 服务是否真正运行在本地
很多人以为双击 mongod.exe 就算启动成功，结果一连就报 Connection refused。根本原因：mongod 默认不自动创建数据目录，也不监听默认端口，更不会后台常驻。
- 必须手动创建数据目录，比如
mkdir C:\data\db（Windows）或mkdir -p /data/db（macOS/Linux） - 启动命令要显式指定路径：
mongod --dbpath C:\data\db，否则它会直接退出并报错Failed to parse command line - 终端窗口不能关——
mongod是前台进程，关窗即停服务；如需后台运行，得加--fork（Linux/macOS）或用 Windows 服务方式 - 验证是否真在听：执行
mongo --eval "db.runCommand({ping:1})"，返回{ "ok" : 1 }才算通
Java 项目里引入正确的 MongoDB 驱动版本
MongoDB 官方 Java 驱动从 4.x 开始彻底弃用 com.mongodb.MongoClient，改用 com.mongodb.client.MongoClient，但很多老教程还在混用，导致编译通过、运行时报 NoClassDefFoundError 或连接失败。
- Maven 依赖必须用最新稳定版，例如：
org.mongodb:mongodb-driver-sync:4.12.1（同步版）或mongodb-driver-reactivestreams（响应式） - 别再引
mongo-java-driver（已废弃），它和新驱动包名、类路径全不同，混用必炸 - Spring Boot 用户注意：
spring-boot-starter-data-mongodb的版本要跟驱动对齐，比如 Spring Boot 3.x 要求驱动 ≥ 4.9 - 连接字符串格式必须带
?appName=xxx（可选但推荐），否则某些集群环境下会因缺少客户端标识被拒绝
初始化 MongoClient 时别写死 new MongoClient()
直接 new MongoClient（尤其传 new MongoClientURI(...)）是反模式。它绕过连接池配置、超时控制，且无法复用，高并发下极易耗尽 socket 或触发 java.net.SocketTimeoutException。
- 正确做法是用
MongoClients.create()，传入MongoClientSettings实例 - 至少设置三项：
applyToSocketSettings（调connectTimeout和readTimeout）、applyToClusterSettings（设hosts）、applyToServerSettings（可选） - 连接字符串里的
connectTimeoutMS=5000不等于代码里没设超时就生效——驱动只认显式配置，URL 参数可能被忽略 -
MongoClient是线程安全的、应全局单例，每次操作都client.getDatabase(...)即可，别封装成工具类反复 new
第一次连不上？先关掉防火墙和 SELinux
开发机连本地 MongoDB 失败，90% 不是代码问题，而是系统级拦截。特别是 macOS Monterey+、Windows 11 更新后，默认启用更严格的网络策略。
立即学习“Java免费学习笔记（深入）”；
- macOS 上检查：
sudo lsof -i :27017看 mongod 是否真在监听；再试telnet localhost 27017，不通就说明被拦了 - Windows 用户注意：
mongod.exe第一次运行会被 Defender 拦住，弹窗点“允许访问”；若静默失败，去「Windows 安全中心 → 防火墙 → 允许应用通过防火墙」手动加白 - Linux 上若启用了 SELinux，
setsebool -P mongod_can_network on才能让 mongod 绑定端口 - 别迷信
127.0.0.1——有些环境绑定的是::1（IPv6），Java 客户端默认优先走 IPv6，可强制加 JVM 参数：-Djava.net.preferIPv4Stack=true
