Nest.js中跨文件访问封装的process.env环境变量为undefined的问题

问题场景 #

• 项目中新建独立的auth.parameters.ts文件，直接在模块顶层导出配置对象，通过process.env.CUSTOM_VAR给对象属性赋值
• 其他业务模块中通过import { SecurityParameters } from '../auth/auth.parameters'导入该模块，读取SecurityParameters.somevar时得到undefined
• 直接在业务代码内书写process.env.CUSTOM_VAR可以正常读取到环境变量值，只有封装在独立配置文件中跨文件导入后取值异常
• 此前测试发现只有在类内部声明对应变量时，环境变量才能被正常识别，因此计划抽离独立配置文件统一管理参数

问题根因 #

• 核心原因是模块加载时序冲突。Nest.js 项目通常通过@nestjs/config或者dotenv在应用启动阶段解析.env文件，将配置写入process.env，这个解析过程是异步的。而独立定义的auth.parameters.ts属于普通ES模块，会在编译加载阶段（也就是应用启动流程还没走到环境变量解析环节）就被执行，这时候process.env.CUSTOM_VAR还没完成写入，赋值给对象属性的自然是undefined。哪怕后续环境变量加载完成，已经初始化好的静态对象属性也不会自动更新值。
• 附带代码层面的匹配问题。当前auth.parameters.ts中导出的对象名是obj，但导入时使用的标识是SecurityParameters，即使时序问题解决，这种导出和导入命名不匹配的写法，也会因为找不到对应的导出绑定，最终拿到undefined。

对应解决方法 #

1. 改为动态读取属性，避免模块加载时静态赋值 #

不要在模块顶层就把process.env的值写入静态对象，改成属性访问时再动态取值：

// auth.parameters.ts
export const SecurityParameters = {
  // 用getter定义属性，访问时才执行取值逻辑
  get somevar() {
    return process.env.CUSTOM_VAR;
  }
}

这种写法不需要调整原有导入逻辑，等到真正读取somevar属性时，环境变量已经完成加载，就能拿到正确值。

2. 统一使用Nest.js的ConfigService管理配置 #

不要自行抽离独立的静态配置文件，将环境变量读取逻辑交给Nest生态内置的配置能力处理：

• 在根模块最外层优先导入全局配置模块，确保环境变量在应用启动最早期就完成注入：

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // 全局可注入，无需在每个模块单独导入
      envFilePath: '.env',
    }),
    AuthModule,
  ]
})
export class AppModule {}

• 在需要读取配置的业务类中，通过依赖注入获取ConfigService实例，再读取对应环境变量，不要在模块顶层直接读process.env：

@Injectable()
export class SomeBusinessService {
  // 注入全局配置服务
  constructor(private configService: ConfigService) {}

  getCustomVar() {
    return this.configService.get<string>('CUSTOM_VAR');
  }
}

3. 调整模块加载顺序，保证环境变量优先完成解析 #

如果一定要在独立文件中定义静态配置对象，需要确保auth.parameters.ts的加载时机在环境变量解析完成之后。可以在项目入口文件的最顶部，先执行环境变量解析逻辑，再导入其他业务模块：

// main.ts 文件最开头，在所有业务导入之前
import * as dotenv from 'dotenv';
// 第一时间解析.env文件，把配置写入process.env
dotenv.config();

// 之后再导入业务依赖，这时候加载auth.parameters.ts时，process.env.CUSTOM_VAR已经存在
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

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