本文详解如何在 next.js（app router）中避免每次请求重复建立 mongodb 连接，通过复用已存在的 mongoose 连接实现单例式初始化，确保服务启动时仅连接一次数据库。
本文详解如何在 next.js（app router）中避免每次请求重复建立 mongodb 连接，通过复用已存在的 mongoose 连接实现单例式初始化，确保服务启动时仅连接一次数据库。
在 Next.js 的 App Router 架构中，服务器组件和 Route Handlers（如 app/route.ts）并非像传统 Express 那样拥有明确的“应用启动入口”。每个 Route Handler 默认以无状态、按需执行的方式运行——这意味着若将 mongoose.connect() 直接写在模块顶层或处理函数中，它可能在每次 HTTP 请求时被重复调用，不仅造成性能浪费，更会触发 Mongoose 的连接警告（如 MongoServerSelectionError 或连接泄漏），甚至导致连接数激增。
正确的做法是：利用 Mongoose 内置的连接状态管理机制，实现连接的惰性初始化与复用。核心原理在于 —— Mongoose 实例及其底层连接（mongoose.connection）在 Node.js 进程内是单例的；只要不显式调用 disconnect()，连接一旦建立就会持续复用。我们只需在每次需要时检查 readyState，仅当未连接（0）或正在连接（2）时才发起新连接。
以下是一个生产就绪的数据库连接封装示例（推荐存为 lib/mongodb.ts）：
// lib/mongodb.ts
import mongoose from 'mongoose';
const MONGODB_URI = process.env.MONGODB_URI;
if (!MONGODB_URI) {
throw new Error('Please define the MONGODB_URI environment variable');
}
let cached = global.mongoose;
if (!cached) {
cached = global.mongoose = { conn: null, promise: null };
}
export async function connectToDatabase() {
if (cached.conn) {
return cached.conn;
}
if (!cached.promise) {
const opts = {
bufferCommands: false,
maxPoolSize: 10,
serverSelectionTimeoutMS: 5000,
socketTimeoutMS: 45000,
family: 4, // Use IPv4 only
};
cached.promise = mongoose
.connect(MONGODB_URI, opts)
.then((mongoose) => {
console.log('✅ MongoDB connected successfully');
return mongoose;
});
}
try {
cached.conn = await cached.promise;
} catch (e) {
cached.promise = null;
throw e;
}
return cached.conn;
}✅ 关键设计说明：
- 使用 global.mongoose 缓存连接实例，避免多模块重复初始化（Next.js 的热重载和 Serverless 环境下尤其重要）；
- cached.promise 确保并发请求不会触发多次 connect() 调用；
- 显式配置连接池与超时参数，提升稳定性；
- 错误发生后主动重置 promise，防止后续请求永远等待失败的 Promise。
在 Route Handler 中使用时，只需导入并调用该函数（注意：不要在模块顶层直接调用 connect()）：
// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { connectToDatabase } from '@/lib/mongodb';
import User from '@/models/User'; // 假设你已定义 Mongoose Model
export async function GET() {
try {
await connectToDatabase(); // ✅ 仅首次调用真正连接，后续直接返回缓存连接
const users = await User.find({}).limit(10);
return NextResponse.json({ data: users });
} catch (error) {
console.error('Failed to fetch users:', error);
return NextResponse.json(
{ error: 'Failed to load users' },
{ status: 500 }
);
}
}⚠️ 重要注意事项：
- 不要在客户端组件中使用此逻辑：Mongoose 是服务端专属，严禁暴露数据库连接逻辑至浏览器；
- 环境一致性：确保 MONGODB_URI 在开发、预览与生产环境均正确配置（推荐使用 .env.local + process.env）；
- Serverless 兼容性：Vercel 等平台会复用 Lambda 实例，上述缓存方案可有效跨请求复用连接；但若函数冷启动频繁，建议启用 Vercel 的 Edge Config 或 Durable Objects 做连接池优化；
- 连接清理（可选）：Next.js 当前不提供标准的 onShutdown 钩子，如需优雅断开（例如本地开发时 Ctrl+C），可监听 process.on('SIGTERM')，但生产环境通常无需手动断开。
总结而言，Next.js 并非“无法”实现启动时初始化，而是需适配其基于请求生命周期的设计范式。通过状态检查 + 全局缓存 + 惰性连接，你完全可以获得与 Express 相同的高效、可靠数据库连接体验——既符合框架哲学，又保障了应用性能与稳定性。
