Node.js重构旧API时数据库连接为null的问题排查

一、先解决 process.env 变量 undefined 问题 #

不管是否使用 async/await，环境变量取不到都是加载时机错误导致的，先把这个问题根治：

• 如果用 CommonJS 模块：
  在所有代码最顶部（包括数据库连接模块）加载 dotenv：

  // 放在文件第一行，确保其他模块加载前环境变量已就绪
  require('dotenv').config({ path: './.env' }); // 可指定.env路径，默认找项目根目录
  

• 如果用 ESM 模块（Node.js 14+）：

  import dotenv from 'dotenv';
  dotenv.config();
  // 或者 Node.js 20+ 直接用命令行参数启动：node --env-file=.env app.js，无需手动加载dotenv
  

二、解决数据库连接对象在接口中 undefined 的问题 #

核心原因是异步连接初始化未完成时，接口就提前调用了未就绪的连接对象，通过以下两种方式解决：

方式1：封装异步获取连接的函数（推荐） #

把连接逻辑封装成一个单例函数，确保每次调用都返回已建立的连接：

// db.js
require('dotenv').config();
const mysql = require('mysql2/promise'); // 以mysql2为例，其他数据库库逻辑类似

let dbConnection;

async function getDbConnection() {
  // 单例模式：如果连接已存在，直接返回
  if (dbConnection) return dbConnection;

  // 首次建立连接
  try {
    dbConnection = await mysql.createConnection({
      host: process.env.DB_HOST,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
      database: process.env.DB_NAME
    });
    console.log('数据库连接成功');
    return dbConnection;
  } catch (err) {
    console.error('数据库连接失败:', err);
    throw err; // 抛出错误让上层处理
  }
}

module.exports = { getDbConnection };

在接口中调用时，必须用 await 获取连接：

// 路由文件
const { getDbConnection } = require('./db');

app.get('/api/users', async (req, res) => {
  try {
    const connection = await getDbConnection();
    const [rows] = await connection.execute('SELECT * FROM users');
    res.json(rows);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

方式2：启动服务器前预初始化连接 #

如果希望服务器启动前就确保连接就绪，可在启动入口先完成连接初始化：

// app.js
require('dotenv').config();
const { getDbConnection } = require('./db');
const express = require('express');
const app = express();

async function startServer() {
  // 先确保数据库连接成功
  await getDbConnection();
  
  // 再启动服务器
  app.listen(process.env.PORT || 3000, () => {
    console.log(`服务器运行在端口 ${process.env.PORT || 3000}`);
  });
}

// 捕获启动失败的错误
startServer().catch(err => {
  console.error('服务器启动失败:', err);
  process.exit(1);
});

这种方式下，接口中调用 getDbConnection() 会直接返回已建立的连接，无需等待初始化。

三、避坑提醒 #

• 不要直接在模块顶层用 await 导出连接对象（除非用 ESM 的顶层 await），CommonJS 模块不支持顶层 await，强行使用会导致导出的是 Promise 对象而非连接实例，接口调用时会出现 undefined 或方法调用失败。
• 单例模式要处理连接断开的情况：如果连接意外断开，可在函数中增加连接状态检查，重新建立连接。

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