TypeScript泛型函数无默认值时返回unknown类型问题

问题场景 #

我尝试编写一个用于获取环境变量的泛型函数，现有代码如下：

export interface Config {
  readonly PORT: number;
  readonly DATABASE_URL: string;
  // ... 其他字段
}
const config: Config = Object.freeze({
  ENVIRONMENT,
  PROJECT_NAME,
  PORT: parseInt(getEnvVariable('PORT', '9000'), 10),
  DATABASE_URL: getEnvVariable('DATABASE_URL'),
  AWS_REGION,
});

function getEnvVariable<T>(name: string, defaultValue?: T): T | string {
  const val = process.env[name];

  if (val) {
    return val;
  }

  if (defaultValue) {
    return defaultValue;
  }

  throw new Error(`Missing environment variable: ${name}`);
}

当前收到错误提示：

Type 'Readonly<{ ENVIRONMENT: string; PROJECT_NAME: string; PORT: number; DATABASE_URL: unknown; AWS_REGION: string; }>' is not assignable to type 'Config'.
  Types of property 'DATABASE_URL' are incompatible.
    Type 'unknown' is not assignable to type 'string'.

当defaultValue参数为undefined时，即便函数内有真值检查，仍会出现此错误。如何在不使用''作为defaultValue的前提下修复该问题？

修复方案 #

问题根源是泛型类型推导失效：不传defaultValue时，TypeScript会将泛型T推断为unknown，导致返回类型变成unknown | string，无法匹配Config中DATABASE_URL的string类型要求。下面提供两种可行修复方式：

方案1：函数重载（推荐） #

通过定义不同参数签名的重载，明确告知类型系统两种场景下的返回值类型：

• 不带默认值时，函数要么返回环境变量的string值，要么抛出错误，因此直接返回string
• 带默认值时，返回默认值类型或string

export interface Config {
  readonly PORT: number;
  readonly DATABASE_URL: string;
  // ... 其他字段
}

// 重载签名1：无默认值，返回string
function getEnvVariable(name: string): string;
// 重载签名2：有默认值，返回T | string
function getEnvVariable<T>(name: string, defaultValue: T): T | string;
// 函数实现
function getEnvVariable<T>(name: string, defaultValue?: T): T | string {
  const val = process.env[name];

  if (val) {
    return val;
  }

  // 改用严格判断undefined，避免空字符串、0等合法默认值被误判
  if (defaultValue !== undefined) {
    return defaultValue;
  }

  throw new Error(`Missing environment variable: ${name}`);
}

const config: Config = Object.freeze({
  ENVIRONMENT,
  PROJECT_NAME,
  PORT: parseInt(getEnvVariable('PORT', '9000'), 10),
  DATABASE_URL: getEnvVariable('DATABASE_URL'), // 现在类型推断为string，符合要求
  AWS_REGION,
});

方案2：泛型默认值+条件类型 #

给泛型T设置默认类型为never，通过条件类型动态推导返回值类型：

export interface Config {
  readonly PORT: number;
  readonly DATABASE_URL: string;
  // ... 其他字段
}

function getEnvVariable<T = never>(name: string, defaultValue?: T): T extends never ? string : T | string {
  const val = process.env[name];

  if (val) {
    return val as T extends never ? string : T | string;
  }

  if (defaultValue !== undefined) {
    return defaultValue as T extends never ? string : T | string;
  }

  throw new Error(`Missing environment variable: ${name}`);
}

const config: Config = Object.freeze({
  ENVIRONMENT,
  PROJECT_NAME,
  PORT: parseInt(getEnvVariable('PORT', '9000'), 10),
  DATABASE_URL: getEnvVariable('DATABASE_URL'),
  AWS_REGION,
});

关键注意点 #

• TypeScript无法自动识别“抛出错误后函数不会返回undefined”的逻辑，必须通过重载或条件类型显式声明返回值类型
• 原代码中if (defaultValue)的判断存在漏洞，会过滤掉''、0这类合法默认值，建议改为defaultValue !== undefined

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