如何解决TypeScript泛型报错？实现入参与返回类型匹配

我想要实现一个接收string | undefined类型参数且返回同类型结果的函数sanitizeName。最初的写法如下：

sanitizeName: (name: string | undefined): string | undefined => {
  return name?.replace(...)
},

但当传入string类型参数时，我确定返回值应为string，但当前返回类型仍为string | undefined，需要额外做存在性检查。

于是尝试使用泛型<T extends string | undefined>，将参数和返回类型都设为T：

sanitizeName: <T extends string | undefined>(name: T): T => {
  return name?.replace(...)
},

本以为这样传入undefined返回undefined，传入string返回string，却出现了如下报错：

Type 'string | undefined' is not assignable to type 'T'.
  'string | undefined' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'string | undefined'.
    Type 'undefined' is not assignable to type 'T'.
      'undefined' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'string | undefined'.ts(2322)

报错原因 #

泛型约束T extends string | undefined允许T是string | undefined的子类型，比如具体的字符串字面量类型（如"Alice"）。此时name?.replace(...)的返回类型是string | undefined，但如果T是更具体的字面量类型，string无法赋值给该字面量类型，TypeScript因此抛出类型不兼容的错误。本质是你的泛型写法让TypeScript认为T可能是比string | undefined更窄的类型，而返回值无法匹配所有可能的T子类型。

实现预期行为的两种方式 #

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

通过重载明确不同入参对应的返回类型，TypeScript会自动匹配：

// 重载签名
sanitizeName(name: string): string;
sanitizeName(name: undefined): undefined;
// 实现签名
sanitizeName(name: string | undefined): string | undefined {
  // 替换为你的实际正则替换逻辑
  return name?.replace(/\s+/g, "-");
}

使用时，传入string类型参数会得到string返回值，传入undefined则返回undefined，无需额外类型检查。

方式2：条件类型 #

用条件类型让返回类型和入参类型严格绑定，配合类型断言辅助类型推断：

const sanitizeName = <T extends string | undefined>(
  name: T
): T extends string ? string : undefined => {
  return name?.replace(/\s+/g, "-") as T extends string ? string : undefined;
};

这种方式通过条件类型精确映射入参与返回类型，类型断言用于告诉TypeScript返回值符合条件类型的结果。

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