当前位置：首页 > news >正文

NestJS Config 入门教程

news 2025/8/10 5:14:47

什么是 NestJS Config？

NestJS Config 是官方提供的配置管理模块，基于 dotenv 和 @nestjs/config 包实现，帮助开发者：

集中管理环境变量
支持多环境配置（开发/测试/生产）
类型安全地访问配置
验证配置有效性

快速开始

1. 安装依赖

npm install @nestjs/config dotenv

2. 创建配置文件

在项目根目录创建 .env 文件：

DATABASE_HOST=localhost
DATABASE_PORT=5432
JWT_SECRET=my_secure_secret

3. 基础配置

在 app.module.ts 中注册 ConfigModule：

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';@Module({imports: [ConfigModule.forRoot({isGlobal: true, // 全局可用envFilePath: '.env', // 指定环境文件路径}),],
})
export class AppModule {}

4. 访问配置

在服务中注入 ConfigService：

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';@Injectable()
export class DatabaseService {constructor(private configService: ConfigService) {}getConnection() {return {host: this.configService.get('DATABASE_HOST'),port: this.configService.get<number>('DATABASE_PORT'),};}
}

高级配置

1. 类型安全配置

创建 config.interface.ts：

export interface DatabaseConfig {host: string;port: number;
}export interface AppConfig {jwtSecret: string;database: DatabaseConfig;
}

在 ConfigModule 中注册：

ConfigModule.forRoot({load: [() => ({jwtSecret: process.env.JWT_SECRET,database: {host: process.env.DATABASE_HOST,port: parseInt(process.env.DATABASE_PORT),},})],
});

2. 配置验证

使用 Joi 进行验证：

npm install joi

创建 validation.schema.ts：

import * as Joi from 'joi';export const validationSchema = Joi.object({JWT_SECRET: Joi.string().required(),DATABASE_HOST: Joi.string().required(),DATABASE_PORT: Joi.number().required().default(5432),
});

在 ConfigModule 中应用：

ConfigModule.forRoot({validationSchema,validationOptions: {abortEarly: false, // 显示所有错误},
});

3. 多环境配置

创建不同环境的文件：

.env.development
.env.production
.env.test

通过 NODE_ENV 指定环境：

# 开发环境
NODE_ENV=development npm run start# 生产环境
NODE_ENV=production npm run start:prod

4. 嵌套配置

使用 registerAs 组织复杂配置：

// database.config.ts
export default registerAs('database', () => ({host: process.env.DATABASE_HOST,port: parseInt(process.env.DATABASE_PORT),
}));

在模块中导入：

ConfigModule.forRoot({load: [databaseConfig],
});

访问嵌套配置：

this.configService.get('database.host');

最佳实践

1. 安全第一

在 .gitignore 中添加 .env*
生产环境使用秘密管理工具（AWS Secrets Manager、HashiCorp Vault）
敏感变量使用加密存储

2. 变量命名规范

全大写加下划线（如 STRIPE_API_KEY）
按功能分组（数据库、第三方服务、应用配置）

3. 类型安全

始终为数字类型使用 parseInt 或 parseFloat
使用枚举类型处理有限选项
为布尔值使用 process.env.VAR === 'true'

4. 默认值处理

this.configService.getOrThrow('REQUIRED_VAR');
this.configService.get('OPTIONAL_VAR', { infer: true }) ?? 'default';

5. Docker 集成

在 docker-compose.yml 中传递变量：

environment:- DATABASE_HOST=db-service- DATABASE_PORT=5432

常见问题

1. 变量未加载？

检查 .env 文件路径是否正确
确保 ConfigModule.forRoot() 在根模块注册
变量名是否包含特殊字符（建议仅用字母、数字、下划线）

2. 如何设置默认值？

this.configService.get('PORT', { infer: true }) ?? 3000;

3. 验证失败怎么办？

查看详细错误信息：

try {await ConfigModule.forRoot({validationSchema,});
} catch (e) {console.error('Config validation error:', e);process.exit(1);
}

示例项目结构

project-root/
├── src/
│   ├── config/
│   │   ├── database.config.ts
│   │   └── validation.schema.ts
│   └── app.module.ts
├── .env
├── .env.development
└── .env.production