TypeScript中从环境变量创建动态类型遇process命名空间报错

核心原因 #

TypeScript的类型系统是静态编译时生效的，而process.env是Node.js运行时的全局变量，TS编译阶段无法直接识别它的类型；另外默认情况下TS没有内置Node.js全局变量的类型定义，所以会抛出"Cannot find namespace 'process'"的错误。同时，即使解决了类型定义问题，process.env的值是运行时动态的，也无法直接作为静态类型的字面量使用。

解决方案 #

1. 添加上Node.js的类型定义

首先安装Node.js的类型包：

npm install @types/node --save-dev
# 或者用yarn
yarn add @types/node -D

然后在tsconfig.json的compilerOptions中配置类型引入：

{
  "compilerOptions": {
    "types": ["node"]
  }
}

这样TS就能识别process全局变量的类型了。

2. 将动态环境变量转为静态类型

由于process.env是运行时值，不能直接用于类型定义，需要先将环境变量的值转为静态常量，再基于常量生成类型：

步骤1：创建环境变量常量文件
比如在src/env.ts中加载并导出环境变量常量：

import dotenv from 'dotenv';
// 加载.env文件中的环境变量
dotenv.config();

// 用as const将数组转为只读元组，保留字面量类型
export const NAME_VALUES = [process.env.name1, process.env.name2] as const;

步骤2：基于常量生成类型
在需要定义类型的文件中引入常量并生成类型：

import { NAME_VALUES } from './env';

// 提取元组中的元素类型作为customName的可选值
type Names = { customName: typeof NAME_VALUES[number] };

如果需要确保环境变量一定存在（排除undefined类型），可以在导出常量时添加非空断言或值检查：

export const NAME_VALUES = [process.env.name1!, process.env.name2!] as const;

3. 通过构建工具注入静态环境变量（可选）

如果你的项目使用Webpack、Vite等构建工具，可以通过配置将环境变量转为编译时的静态字符串，这样就能直接在类型中使用：

Webpack示例（使用DefinePlugin）
在webpack.config.js中添加配置：

const webpack = require('webpack');
const dotenv = require('dotenv').config();

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.name1': JSON.stringify(dotenv.parsed.name1),
      'process.env.name2': JSON.stringify(dotenv.parsed.name2),
    }),
  ],
};

Vite示例
在vite.config.ts中配置：

import { defineConfig } from 'vite';
import dotenv from 'dotenv';

const env = dotenv.config().parsed;

export default defineConfig({
  define: {
    'process.env.name1': JSON.stringify(env?.name1),
    'process.env.name2': JSON.stringify(env?.name2),
  },
});

配置完成后，就可以直接在类型中使用：

type Names = { customName: typeof process.env.name1 | typeof process.env.name2 };

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