NestJS创建两个根模块时数据库默认连接找不到问题排查

问题背景 #

常规场景下，通过app.module.ts和main.ts启动NestJS应用可正常运行：

app.module.ts #

import { MiddlewareConsumer, Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import jwt from 'express-jwt';

import config from './config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [config],
      envFilePath: '.env',
    }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => ({ ...configService.get('db') }),
    }),
    GraphqlModule,
  ],
  controllers: [],
})
export class AppModule {
  constructor(private config: ConfigService) {}

  configure(consumer: MiddlewareConsumer) {
    consumer
      .forRoutes('graphql');
  }
}

main.ts #

import { INestApplication } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import compression from 'compression';
import { createConnection } from 'typeorm';

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use(compression());

  const config = app.get(ConfigService);

  if (config.get('pubsub.enable')) {
    const pubsubConnection = await createConnection(
      Object.assign(config.get('db'), { name: 'pubsub' }),
    );
    // ...其他pubsub逻辑
  }

  useContainer(app.select(AppModule), { fallbackOnErrors: true });

  const server = await app.listen(config.get('PORT', ''));
  server.setTimeout(3 * 60 * 1000);
}

bootstrap();

新增AppTestModule（app.test.module.ts）后，启动应用时数据库连接失败，提示找不到默认连接名称（该名称已在config.ts中定义），且main.ts仅导入AppModule。

app.test.module.ts #

import { MiddlewareConsumer, Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import jwt from 'express-jwt';

import config from './config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [config],
      envFilePath: '.env.test',
    }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => ({ ...configService.get('db') }),
    }),
    GraphqlModule,
  ],
  controllers: [],
})
export class AppTestModule {
  constructor(private config: ConfigService) {}

  configure(consumer: MiddlewareConsumer) {
    consumer
      .forRoutes('graphql');
  }
}

相关依赖版本：

"dependencies": {
  "@nestjs/cli": "^8.2.6",
  "@nestjs/common": "^8.4.5",
  "@nestjs/config": "^2.0.1",
  "@nestjs/core": "^8.4.5",
  "@nestjs/graphql": "^9.1.1",
  "@nestjs/platform-express": "^8.4.5",
  "@nestjs/swagger": "^5.2.1",
  "@nestjs/typeorm": "^8.0.2"
},
"devDependencies": {
  "@nestjs/testing": "^8.4.7"
}

问题原因 #

核心问题出在全局模块冲突与Node.js模块缓存机制：

1. 全局ConfigModule被意外覆盖
   AppTestModule中配置了ConfigModule.forRoot({ isGlobal: true })，若该模块被Node.js模块系统加载（比如测试文件或其他依赖文件导入），全局配置会被替换为.env.test的内容。如果.env.test中的数据库连接配置缺失默认连接名称，或与生产环境config.ts的预期不符，就会导致连接失败。

2. TypeOrm连接注册冲突
   两个模块都调用TypeOrmModule.forRootAsync注册默认数据库连接。当AppTestModule被加载时，会尝试覆盖或重复注册默认连接，导致连接配置混乱，最终出现找不到默认连接名称的错误。

3. 模块缓存触发的意外执行
   Node.js会缓存已加载的模块代码，只要有任何文件（哪怕是测试代码）导入过AppTestModule，其内部的ConfigModule.forRoot和TypeOrmModule.forRootAsync就会被执行，影响全局环境配置，进而导致生产环境启动时使用错误的数据库配置。

解决方案 #

针对上述问题，可采取以下修复方式：

• 隔离测试模块的全局配置
  移除AppTestModule中ConfigModule.forRoot的isGlobal: true配置，改为局部使用：

  ConfigModule.forRoot({
    load: [config],
    envFilePath: '.env.test',
    isGlobal: false // 取消全局配置
  })
  

• 避免重复注册默认连接
  在AppTestModule的TypeOrmModule.forRootAsync中指定唯一的测试连接名称：

  TypeOrmModule.forRootAsync({
    name: 'test-db', // 指定测试连接名称
    inject: [ConfigService],
    useFactory: async (configService: ConfigService) => ({ 
      ...configService.get('db'),
      name: 'test-db'
    }),
  })
  

• 确保测试模块仅在测试环境加载
  生产环境代码（包括main.ts及其依赖文件）不要导入AppTestModule，仅在测试入口文件（如test/app.e2e-spec.ts）中导入该模块。

• 统一环境配置加载逻辑
  放弃多模块分别配置ConfigModule，改为根据环境变量动态加载对应env文件，在AppModule中：

  ConfigModule.forRoot({
    isGlobal: true,
    load: [config],
    envFilePath: process.env.NODE_ENV === 'test' ? '.env.test' : '.env',
  })
  

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