Next.js开发中MongoDB活跃连接过多的最佳管理实践

针对你遇到的热重载连接泄漏、异常场景连接未清理问题，以下是经过验证的最佳实践：

1. 验证缓存客户端的有效性，避免复用无效连接 #

现有代码仅检查缓存是否存在，未校验连接是否仍活跃。如果客户端因网络或服务端原因断开，直接复用会导致请求失败。需添加连接状态校验：

// 全局缓存变量，建议挂载到 globalThis 避免模块热重载丢失
let cachedClient: MongoClient | null = null;
let cachedDb: Db | null = null;

export async function connectToDatabase(): Promise<{
  client: MongoClient;
  db: Db;
}> {
  // 检查缓存且连接处于活跃状态
  if (cachedClient && cachedDb) {
    // MongoDB v4+ 用 topology.isConnected() 校验连接状态
    const isConnected = cachedClient.topology?.isConnected();
    if (isConnected) {
      return { client: cachedClient, db: cachedDb };
    }
    // 连接已失效，主动清理缓存并关闭旧连接
    await cachedClient.close();
    cachedClient = null;
    cachedDb = null;
  }

  const client = new MongoClient(MONGODB_URI, {
    // 配置连接池参数，优化资源占用
    maxPoolSize: 10, // 限制连接池大小，开发环境可设为5-10
    minPoolSize: 0, // 空闲时自动释放多余连接
    connectTimeoutMS: 30000,
    socketTimeoutMS: 30000,
    maxIdleTimeMS: 300000, // 闲置5分钟后自动关闭连接
  });

  try {
    await client.connect();
    const db = client.db(MONGODB_DB);
    cachedClient = client;
    cachedDb = db;
    return { client, db };
  } catch (err) {
    // 连接失败时立即关闭客户端，避免缓存无效实例
    await client.close();
    throw err;
  }
}

2. 处理开发环境热重载的连接泄漏 #

Next.js 热重载会重新加载模块，旧模块实例的客户端不会自动关闭，导致连接数持续增长。添加模块卸载钩子，在热重载时主动清理连接：

// 在 mongodb.ts 末尾添加
if (process.env.NODE_ENV === 'development') {
  // 监听模块热重载卸载事件
  if (module.hot) {
    module.hot.dispose(async () => {
      if (cachedClient) {
        await cachedClient.close();
        cachedClient = null;
        cachedDb = null;
      }
    });
  }
}

// 监听进程终止信号，生产环境也适用
process.on('SIGTERM', async () => {
  if (cachedClient) {
    await cachedClient.close();
  }
  process.exit(0);
});

3. 使用全局缓存跨模块复用客户端 #

Next.js 中模块可能被多次加载（尤其是开发环境），将缓存挂载到globalThis可确保不同模块实例共享同一个客户端：

// 扩展全局变量类型声明
declare global {
  var _mongoClient: MongoClient | null;
  var _mongoDb: Db | null;
}

// 优先使用全局变量，避免模块热重载重置缓存
let cachedClient = global._mongoClient || null;
let cachedDb = global._mongoDb || null;

export async function connectToDatabase(): Promise<{
  client: MongoClient;
  db: Db;
}> {
  // ... 原有校验与连接逻辑 ...

  // 连接成功后更新全局变量
  if (!global._mongoClient) {
    global._mongoClient = client;
    global._mongoDb = db;
  }
}

4. 异常场景下的主动清理 #

在业务代码中捕获MongoDB操作异常，当检测到连接失效时主动清理缓存，触发重新连接：

// 示例：API路由中的异常处理
import { connectToDatabase } from '../../lib/mongodb';
import { MongoServerError } from 'mongodb';

export async function GET() {
  try {
    const { db } = await connectToDatabase();
    const data = await db.collection('users').find().toArray();
    return Response.json(data);
  } catch (err) {
    // 检测连接相关异常（如连接断开、认证失败）
    if (err instanceof MongoServerError && [11000, 18, 9001].includes(err.code)) {
      cachedClient = null;
      cachedDb = null;
    }
    return Response.json({ error: '数据获取失败' }, { status: 500 });
  }
}

内容的提问来源于stack exchange，提问作者Eden Berdugo