部署Next.js项目到Vercel/Netlify时Runtime.UnhandledPromiseRejection错误如何解决

错误根因 #

报错核心是两个问题：

1. 调用mongoose.connect()时传入的MongoDB连接URI参数为undefined，不符合字符串类型要求
2. 数据库连接的异步逻辑没有做异常捕获，触发了运行时未处理的Promise拒绝错误

具体修复步骤 #

1. 配置部署平台的环境变量 #

你本地开发用的.env文件默认不会上传到部署平台，需要手动在Vercel、Netlify的后台配置对应变量：

• Vercel配置路径：对应项目 -> Settings -> Environment Variables，新增key为MONGODB_URI的变量，值填你的MongoDB连接字符串，保存后重新部署
• Netlify配置路径：对应项目 -> Site settings -> Environment variables，新增key为MONGODB_URI的变量，值填你的MongoDB连接字符串，保存后触发重新部署
  注意：MONGODB_URI是服务端使用的环境变量，不需要加NEXT_PUBLIC_前缀，加了反而会将敏感的数据库连接信息暴露到客户端

2. 新增环境变量校验逻辑 #

在数据库连接函数开头增加环境变量存在性校验，提前抛出可读性更高的错误，避免传入undefined

3. 增加异步异常捕获 #

给数据库连接逻辑包裹try/catch块，避免未处理的Promise拒绝报错 #

修复后的数据库连接代码示例 #

import mongoose from 'mongoose';

const connection = {};

async function connect() {
  // 新增环境变量校验
  if (!process.env.MONGODB_URI) {
    throw new Error('MONGODB_URI 环境变量未配置，请检查部署平台的环境变量设置');
  }
  if (connection.isConnected) {
    console.log('already connected');
    return;
  }
  if (mongoose.connections.length > 0) {
    connection.isConnected = mongoose.connections[0].readyState;
    if (connection.isConnected === 1) {
      console.log('use previous connection');
      return;
    }
    await mongoose.disconnect();
  }
  try {
    // 新增异常捕获
    const db = await mongoose.connect(process.env.MONGODB_URI, {
      // useNewUrlParser: true,
      // useUnifiedTopology: true,
    });
    console.log('new connection');
    connection.isConnected = db.connections[0].readyState;
  } catch (err) {
    console.error('数据库连接失败：', err);
    throw err;
  }
}

async function disconnect() {
  if (connection.isConnected) {
    if (process.env.NODE_ENV === 'production') {
      await mongoose.disconnect();
      connection.isConnected = false;
    } else {
      console.log('not disconnected');
    }
  }
}

function convertDocToObj(doc) {
  doc._id = doc._id.toString();
  doc.createdAt = doc.createdAt.toString();
  doc.updatedAt = doc.updatedAt.toString();
  return doc;
}

const db = { connect, disconnect, convertDocToObj };
export default db;

额外排查点 #

如果配置完环境变量还是报错，检查以下内容：

• 确认环境变量值没有多余的空格、引号，复制粘贴时不要带多余字符
• 如果你在Next.js的next.config.js里配置了环境变量白名单，确认MONGODB_URI已经被加入配置
• 确认你的数据库连接逻辑仅在服务端执行，不要在客户端组件/客户端生命周期中调用数据库连接方法

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