Next.js搭配MongoDB/mongoose部署Vercel报500错误（本地运行正常）

以下是本地运行正常、Vercel部署报500的高频踩坑点，按出现概率从高到低排序：

• 首先排查MongoDB服务IP白名单配置：本地开发时你的设备公网IP在白名单内因此可以正常连接，但Vercel Serverless函数出口IP为动态池，必须将MongoDB实例的IP访问白名单设置为0.0.0.0/0（允许所有IP访问），IP拦截会直接导致连接失败返回500，和环境变量配置是否正确无关。这是最高发的问题，多数开发者核对完环境变量后会忽略该配置
• 排查Mongoose连接是否做了全局缓存：Vercel采用无状态Serverless架构，若每次getServerSideProps/API路由触发时都新建Mongoose连接，一方面会因连接建立慢触发Vercel免费版10秒的函数执行超时，另一方面会快速耗尽MongoDB连接池上限直接报错。正确的连接复用写法如下，所有数据库操作前必须先调用该连接方法：

// lib/dbConnect.js
import mongoose from 'mongoose'

const MONGODB_URI = process.env.MONGODB_URI
if (!MONGODB_URI) throw new Error('未配置MONGODB_URI环境变量')

let cached = global.mongoose
if (!cached) cached = global.mongoose = { conn: null, promise: null }

export default async function dbConnect() {
  if (cached.conn) return cached.conn
  if (!cached.promise) {
    cached.promise = mongoose.connect(MONGODB_URI, {
      bufferCommands: false,
    })
  }
  cached.conn = await cached.promise
  return cached.conn
}

• 排查Mongoose Model重复注册问题：Serverless函数实例复用时，若每次执行都直接调用mongoose.model(模型名, Schema)注册模型，会抛出OverwriteModelError导致500。所有模型导出需做存在性判断：

// models/Tour.js
import mongoose from 'mongoose'
const tourSchema = new mongoose.Schema({/* 你的Schema定义 */})
export default mongoose.models.Tour || mongoose.model('Tour', tourSchema)

• 排查Vercel环境变量配置有效性：
  • 确认MONGODB_URI等变量已经配置在Vercel对应项目的Production/Preview环境变量中，而非仅存在于本地.env.local文件
  • 若MongoDB连接串的密码中包含@、#、?等特殊字符，必须做URL编码，否则Vercel环境下解析连接串会直接认证失败
• 排查具体错误日志：在getServerSideProps的数据库查询逻辑外层加try/catch，捕获的错误打印到控制台后，去Vercel控制台对应部署的Function Logs中查看具体错误类型，区分是连接超时、认证失败、查询报错还是其他问题，不要仅根据通用500状态码排查。

注意：不要在项目文件顶层直接执行mongoose.connect()初始化连接，必须在服务端执行逻辑（getServerSideProps、API Route、Server Component）内调用封装好的dbConnect方法后再做数据操作。

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