如何在 Next.js 中实现应用启动时仅执行一次的数据库连接逻辑

本文详解如何在 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 相同的高效、可靠数据库连接体验——既符合框架哲学，又保障了应用性能与稳定性。