TypeScript函数重载中instanceof不被识别引发类型错误问题

问题重现 #

以下代码运行时逻辑正常，但在TypeScript v4.5.5中会出现类型错误：

class A {}
class B {}

function testFn(elem: A): 'true';
function testFn(elem: B): false;
function testFn(elem: A | B) {
  if (elem instanceof A) return 'true';

  return false;
}

const val1: 'true' = testFn(new A()); // 正常
const val2: false = testFn(new B()); // 错误：类型'"true"'不能赋值给类型'false'

问题原因 #

核心问题出在TypeScript的结构类型系统：

• 空类A和B没有任何成员，结构完全一致，TypeScript会将它们视为兼容类型。
• 函数重载的匹配逻辑是：编译器会根据调用时的参数类型，匹配第一个符合条件的重载签名。当传入new B()时，因为B和A结构兼容，编译器认为参数同时满足A和B的类型约束，会优先匹配第一个重载（返回'true'），导致类型推断错误。
• 虽然运行时instanceof能正确区分两个类的实例，但编译期TypeScript无法通过空类的结构区分它们，重载匹配逻辑因此失效。

解决方法 #

方法1：给类添加私有成员，启用名义类型区分 #

在类中添加私有属性（或受保护属性），让TypeScript将它们视为不同的名义类型，打破结构兼容性：

class A {
  private _brand: void; // 仅用于类型区分，无需赋值
}
class B {
  private _brand: void; // 私有成员名可以相同，只要是各自类的私有属性即可
}

function testFn(elem: A): 'true';
function testFn(elem: B): false;
function testFn(elem: A | B) {
  if (elem instanceof A) return 'true';

  return false;
}

const val1: 'true' = testFn(new A()); // 正常
const val2: false = testFn(new B()); // 正常

方法2：移除重载，让返回值自动推断 #

如果不需要显式的重载签名，可以直接依靠TypeScript的控制流分析自动推断返回类型，避免重载匹配的问题：

class A {}
class B {}

function testFn(elem: A | B) {
  if (elem instanceof A) return 'true' as const; // 使用as const固定字面量类型

  return false as const;
}

const val1 = testFn(new A()); // 类型自动推断为'true'
const val2 = testFn(new B()); // 类型自动推断为false

方法3：使用类型谓词明确类型判断 #

如果需要在函数外部也能区分类型，可以结合类型谓词：

class A {}
class B {}

function isA(elem: A | B): elem is A {
  return elem instanceof A;
}

function testFn(elem: A | B) {
  return isA(elem) ? 'true' as const : false as const;
}

const val1 = testFn(new A()); // 'true'
const val2 = testFn(new B()); // false

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