TypeScript应用程序配置管理：完整指南

TypeScript应用程序配置：从简单到复杂

任何现代应用程序都需要灵活且安全的配置。无论是API密钥、数据库连接参数、服务器端口还是功能标志——配置应与代码分离，易于阅读并在启动时进行验证。在TypeScript世界中，这项任务有其特殊性：配置的类型化提供了自动补全功能并防止运行时错误。在本文中，我们将探讨管理TypeScript应用程序配置的最佳实践、流行库和工具。

为什么不应直接使用process.env？

乍一看，通过process.env读取环境变量似乎是一个简单的解决方案。然而，这种方法存在重大缺陷：

• 缺乏类型化：所有值都是字符串，即使逻辑上应该是数字或布尔值。
• 拼写错误风险：很容易将process.env.DB_HOTS写成DB_HOST，从而得到undefined。
• 缺乏验证：如果必需的变量未设置，应用程序会在最意想不到的时刻崩溃，而不是在启动时。

良好的配置可以解决所有这些问题。

dotenv库及其TypeScript封装

加载.env文件的事实标准是dotenv库。对于TypeScript，使用支持多个环境（development、staging、production）的dotenv-flow或dotenv-expand会很方便。

// 安装// npm install dotenv dotenv-expand

// config/env.tsimport dotenv from 'dotenv';import dotenvExpand from 'dotenv-expand';

const myEnv = dotenv.config({ path: `.env.${process.env.NODE_ENV || 'development'}` });dotenvExpand.expand(myEnv);

调用此函数后，.env文件中的所有变量将通过process.env可用，但我们仍然没有类型。

使用Zod进行模式验证

Zod是一个强大的库，用于声明式模式验证，并具有一流的TypeScript支持。它非常适合配置：

// config/schema.tsimport { z } from 'zod';

const envSchema = z.object({  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),  PORT: z.coerce.number().positive().default(3000),  DATABASE_URL: z.string().url(),  JWT_SECRET: z.string().min(32),  REDIS_HOST: z.string().default('localhost'),  REDIS_PORT: z.coerce.number().default(6379),  FEATURE_NEW_UI: z    .string()    .transform((val) => val === 'true')    .default('false'),});

export type EnvConfig = z.infer<typeof envSchema>;

现在，我们可以在启动时安全地解析和验证环境：

// config/index.tsimport { envSchema, EnvConfig } from './schema';

let config: EnvConfig;

export function loadConfig(): EnvConfig {  if (config) return config; // 缓存

  const result = envSchema.safeParse(process.env);  if (!result.success) {    console.error('❌ 无效的环境变量:', result.error.flatten().fieldErrors);    process.exit(1);  }  config = result.data;  return config;}

export function getConfig(): EnvConfig {  if (!config) throw new Error('配置未加载。请先调用 loadConfig()。');  return config;}

用于管理应用程序配置的Conf库

如果您的应用程序不仅需要读取配置，还需要写入配置（例如，用户设置、缓存），请关注Sindre Sorhus的conf。它将数据存储在JSON文件中，并且完全类型化。

// 安装// npm install conf

import Conf from 'conf';

interface AppConfig {  lastOp