如何在Node.js项目构建阶段检测缺失环境变量并抛出错误

完全可行，你可以通过编写独立的环境变量检查脚本，并将其整合到构建流程中，在TypeScript编译前完成校验，中断异常构建。具体步骤如下：

1. 准备依赖 #

首先安装所需的开发依赖：

npm install dotenv ts-node typescript --save-dev

• dotenv：用于加载.env文件中的环境变量
• ts-node：直接运行TypeScript脚本，无需先编译

2. 编写环境变量检查脚本 #

在项目根目录创建check-env.ts文件，内容如下：

import dotenv from 'dotenv';
import fs from 'fs';

// 加载根目录下的.env文件，若文件不存在直接抛出错误
if (!fs.existsSync('.env')) {
  console.error('Error: .env文件不存在');
  process.exit(1);
}

dotenv.config({ path: '.env' });

// 定义所有必须配置的环境变量列表
const REQUIRED_ENV_VARS = ['SOME_KEY', 'OTHER_REQUIRED_VAR'];

// 筛选出缺失的变量
const missingVars = REQUIRED_ENV_VARS.filter(varName => !process.env[varName]);

if (missingVars.length > 0) {
  console.error(`Error: 以下必要环境变量缺失：${missingVars.join(', ')}`);
  process.exit(1); // 以非0状态码退出，中断后续构建流程
}

console.log('✅ 所有必要环境变量配置正常');

3. 整合进构建流程 #

修改package.json中的scripts字段，将检查命令放在构建命令之前：

{
  "scripts": {
    "check-env": "ts-node check-env.ts",
    "build": "npm run check-env && tsc"
  }
}

这样每次执行npm run build时，会先运行检查脚本，只有当所有环境变量都配置正确时，才会继续执行TypeScript编译。

4. 可选：多环境适配 #

如果项目区分开发、生产等不同环境（对应.env.development、.env.production），可以修改脚本支持指定环境参数：

import dotenv from 'dotenv';
import fs from 'fs';

// 从命令行参数获取目标环境，默认使用开发环境
const env = process.argv[2] || 'development';
const envPath = `.env.${env}`;

if (!fs.existsSync(envPath)) {
  console.error(`Error: ${envPath}文件不存在`);
  process.exit(1);
}

dotenv.config({ path: envPath });

const REQUIRED_ENV_VARS = ['SOME_KEY', 'OTHER_REQUIRED_VAR'];
const missingVars = REQUIRED_ENV_VARS.filter(varName => !process.env[varName]);

if (missingVars.length > 0) {
  console.error(`Error: ${env}环境下缺失以下变量：${missingVars.join(', ')}`);
  process.exit(1);
}

console.log(`✅ ${env}环境所有必要变量配置正常`);

然后修改package.json的脚本：

{
  "scripts": {
    "check-env:dev": "ts-node check-env.ts development",
    "check-env:prod": "ts-node check-env.ts production",
    "build:dev": "npm run check-env:dev && tsc",
    "build:prod": "npm run check-env:prod && tsc"
  }
}

5. 可选：类型安全优化 #

为了在TypeScript代码中获得环境变量的类型提示，可以在项目中添加类型声明文件（比如env.d.ts）：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      SOME_KEY: string;
      OTHER_REQUIRED_VAR: string;
    }
  }
}

export {};

这样在使用process.env.SOME_KEY时，TypeScript会自动校验类型，避免拼写错误或未定义的变量引用。

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