TypeScript TS2345：泛型T可实例化为不同约束子类型报错解决

报错产生原因 #

这个错误是TypeScript针对泛型子类型的安全校验机制触发的，核心逻辑如下：

• 泛型参数T在函数被调用时就会被完全确定，它可以是类型约束Value下的任意子类型，不止是基础的number/string/string[]，还包括更窄的字面量类型、元组类型等。
• 函数内部的typeof类型守卫只能收窄变量v本身的类型，不会同步收窄泛型T的实际类型。

TS拦截这类调用是为了避免真实的类型错误，举几个实际会出问题的场景就能理解：

• 如果调用时传入v: 1，TS会推导T为字面量类型1（属于number的子类型），此时cb要求入参必须是字面量1，但分支里计算出的v+1是2，完全不符合cb的入参要求。
• 如果调用时传入v: "John"，TS会推导T为字面量类型"John"，cb要求入参必须是"John"，但分支里拼接后的Hi John是全新的字符串值，不符合类型要求。
• 如果调用时传入v: ["a"]，TS会推导T为元组类型[string]（属于string[]的子类型），cb要求入参必须是长度为1的元组，分支里展开追加元素后得到的是长度不固定的普通数组，也不符合要求。

分支中构造的新值只满足Value的基础类型约束，没法保证一定匹配调用方传入的具体T子类型，TS出于类型安全考虑就会抛出TS2345错误。
另外原问题提供的第三个调用示例本身存在类型错误：Value定义的数组类型是string[]，但示例中cb的入参标注为number[]，正常调用时TS会直接提示类型不匹配。

type Value = string | number | string[];

const fn = <T extends Value>(p: {v: T; cb: (v: T) => void}) => {
  const {v, cb} = p;

  if (typeof v === 'number') {
    cb(v + 1); // TS2345: Argument of type 'number' is not assignable to parameter of type 'T'.
  } else if (typeof v === 'string') {
    cb(`Hi ${v}`); // TS2345
  } else {
    cb([...v, 1]); // TS2345
  }
};

// 调用示例（第三个调用本身存在类型错误）
fn({
  v: 1,
  cb: (n: number) => {
    console.log(n);
  },
});

fn({
  v: 'John',
  cb: (n: string) => {
    console.log(n);
  },
});

fn({
  v: [],
  cb: (n: number[]) => { // 此处TS会报错：number[]和string[]不匹配
    console.log(n);
  },
});

方案1：可辨识联合类型（最推荐，无类型安全隐患） #

放弃泛型定义，将入参拆分为v和cb类型一一对应的联合结构，TS可以通过v的类型守卫自动匹配对应分支的cb类型，既不会报错，也能完整保留类型安全：

type Value = string | number | string[];
// 定义v与cb类型严格绑定的联合参数
type FnParam =
  | { v: number; cb: (v: number) => void }
  | { v: string; cb: (v: string) => void }
  | { v: string[]; cb: (v: string[]) => void };

const fn = (p: FnParam) => {
  const { v, cb } = p;
  if (typeof v === 'number') {
    cb(v + 1);
  } else if (typeof v === 'string') {
    cb(`Hi ${v}`);
  } else {
    cb([...v, 'newItem']);
  }
};

// 调用时类型自动推导正常
fn({
  v: 1,
  cb: (n) => console.log(n), // n推导为number
});
fn({
  v: 'John',
  cb: (s) => console.log(s), // s推导为string
});
fn({
  v: ['hello'],
  cb: (arr) => console.log(arr), // arr推导为string[]
});

方案2：函数重载 #

如果偏好分开传参而非传入对象，可以使用TS函数重载特性，提前声明不同入参对应的类型匹配规则，函数实现内部用宽泛的联合类型编写逻辑即可：

type Value = string | number | string[];
// 重载签名
function fn(v: number, cb: (v: number) => void): void;
function fn(v: string, cb: (v: string) => void): void;
function fn(v: string[], cb: (v: string[]) => void): void;
// 实现签名
function fn(v: Value, cb: (v: Value) => void) {
  if (typeof v === 'number') {
    cb(v + 1);
  } else if (typeof v === 'string') {
    cb(`Hi ${v}`);
  } else {
    cb([...v, 'newItem']);
  }
}

方案3：类型断言（有安全隐患，仅适合可控场景） #

如果能100%保证调用方不会传入字面量、元组这类比基础类型更窄的子类型，可以用类型断言强制告知TS传入值符合T类型，写法最简单，但会跳过TS的部分校验，一旦出现不符合预期的调用会产生隐藏的运行时风险：

type Value = string | number | string[];

const fn = <T extends Value>(p: { v: T; cb: (v: T) => void }) => {
  const { v, cb } = p;
  if (typeof v === 'number') {
    cb((v + 1) as T);
  } else if (typeof v === 'string') {
    cb(`Hi ${v}` as T);
  } else {
    cb([...v, 'newItem'] as T);
  }
};

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