TypeScript 的类型兼容性采用结构化子类型原则，判断一个对象字面量能不能赋给某个接口时，编译器会逐个成员比较类型。当接口里出现了重载方法，这条规则会变得非常严格：对象字面量提供的方法实现必须同时满足所有重载签名，否则就会收到 Type 'xxx' is not assignable to type 'yyy' 之类的错误。这种错误往往让开发者困惑，因为代码逻辑可能完全正确，只是类型声明不够精确。
要弄明白这个现象，得先理解函数类型兼容性和重载签名检查的具体机制。函数类型兼容性判断中，参数类型在方法位置默认是双变的（bivariant），开启 strictFunctionTypes 后函数属性位置变成逆变（contravariant），返回值始终是协变。对象字面量方法属于接口的方法签名，遵循双变规则；但重载方法的检查又会把这些规则叠加起来，导致实现函数必须足够宽泛，覆盖所有调用签名。下面从底层规则开始拆解。
一、函数类型兼容性如何影响对象字面量赋值
TypeScript 采用结构化子类型，而不是名义类型。一个对象可以被赋值给目标类型，只要它拥有目标类型要求的所有成员，并且每个成员的类型都兼容。对于函数成员来说，兼容性规则远比普通属性复杂：函数参数个数可以少于期望值，但参数类型和返回值类型必须满足特定的变型关系。在方法签名位置，参数类型是双变的，也就是说参数类型可以更宽松，也可以更具体，只要两者存在赋值关系即可。返回值则是协变，子类型可以赋给父类型返回位置。
看一个典型示例，区分方法签名和函数属性各自的行为差异：
interface Animal { name: string }
interface Dog extends Animal { bark(): void }
interface Example {
method(x: Dog): void;
prop: (x: Dog) => void;
}
const obj: Example = {
method(x: Animal) {},
prop: function (x: Animal) {} // 错误：参数类型不兼容
};
上面的 method 是方法签名，参数 x 使用 Animal 也能通过检查，因为方法位置的参数是双变的，Dog 和 Animal 之间存在父子关系，编译器允许这种替换。而 prop 是函数属性，当开启 strictFunctionTypes 后参数采用逆变检查，要求函数参数类型必须是期望参数类型的父类型或相同类型。由于 Animal 是 Dog 的父类型，按理说逆变应该允许，但这里的错误发生在反向赋值：属性声明的是 (x: Dog) => void，你提供的是 (x: Animal) => void，参数类型从 Dog 变为 Animal 是在做放宽，逆变规则下不允许。这个细节对于理解后续重载检查至关重要。
二、对象字面量方法重载的检查流程
接口中的重载方法只声明调用签名，没有实现签名。例如 interface 里连续声明两个 convert 方法，编译器看到的是两个独立的调用签名，而不是一个带联合参数的实现函数。当你用对象字面量赋值时，你只能提供 一个 具体的函数实现，这个实现的类型会被推断为单一函数签名。编译器接下来会逐一检查这个实现函数是否兼容每一个重载签名，而不是检查它是否兼容一个合并后的“重载类型”。
下面这个例子会报错，因为它无法同时满足两个重载签名的返回值要求：
interface Converter {
convert(value: string): string;
convert(value: number): number;
}
const converter: Converter = {
convert: function (value: string | number): string | number {
if (typeof value === 'string') return value.toUpperCase();
return value * 2;
}
};
这里实现函数的返回值类型是 string | number。对于第一个重载签名 convert(value: string): string，要求返回值必须是 string 的子类型，但 string | number 显然不是 string 的子类型，所以报错。对于第二个重载签名，返回值又必须是 number 的子类型，string | number 也不是 number 的子类型，同样报错。参数部分因为采用了联合类型 string | number，在双变规则下能够兼容两个签名，所以参数不是问题，错误集中在返回值上。
如果重载方法的返回值相同，参数使用更宽泛的联合类型，实现往往可以通过检查：
interface Formatter {
format(value: string): string;
format(value: number): string;
}
const formatter: Formatter = {
format: function (value: string | number): string {
if (typeof value === 'string') {
return value.trim();
}
return value.toFixed(2);
}
};
这个例子中返回类型统一为 string，实现函数也返回 string，因此协变检查通过。参数 string | number 同时覆盖了 string 和 number，双变条件下兼容。由此可以总结出对象字面量方法重载的检查要点：返回值必须比每个重载签名更具体或相同；参数则要足够宽泛，至少能接受每个重载签名要求的参数类型，否则就会触发“签名不兼容”的错误。
三、常见陷阱与解决方案
一个很容易踩的坑是：对象字面量语法本身并不支持直接声明方法重载。你无法在对象字面量里写两个 map 方法签名再给一个实现，只能老老实实提供一个具体函数。这导致很多开发者误以为可以用对象字面量直接复制接口里的重载声明，结果发现报一堆错。实际上对象字面量中的方法定义只能有一个实现，所以参数和返回值必须人工设计成能同时覆盖所有重载的形式。
最稳妥的做法是先在外部声明一个带有重载签名的函数，再把该函数赋值给对象字面量。函数声明可以拥有多个重载签名和一个实现签名，编译器会根据重载签名生成函数类型，赋值给对象时就能通过检查：
interface Mapper {
map(value: string): number;
map(value: number): string;
}
function mapper(value: string): number;
function mapper(value: number): string;
function mapper(value: string | number): number | string {
if (typeof value === 'string') return value.length;
return String(value);
}
const obj: Mapper = {
map: mapper
};
如果不想额外声明函数，也可以使用类型断言把整个对象字面量断言为目标接口类型。这种方法最简单，但也会绕过一部分编译期检查，如果实现函数确实不满足某个签名，运行期可能会出现意外返回类型，因此只建议在确实有把握的情况下使用：
const obj = {
map: function (value: string | number): number | string {
if (typeof value === 'string') return value.length;
return String(value);
}
} as Mapper;
另一种更符合面向对象习惯的方案是用类实现接口。类方法声明同样支持多重签名，而且实现签名必须兼容所有重载签名，这与接口的行为一致：
class MapperImpl implements Mapper {
map(value: string): number;
map(value: number): string;
map(value: string | number): number | string {
if (typeof value === 'string') return value.length;
return String(value);
}
}
类实现的优势在于代码结构清晰，重载签名和实现放在一起，编译器能同时检查实现签名是否兼容所有重载。缺点是需要额外的类定义，不适合所有场景。总体来说，如果对象只使用一次，类型断言可以接受；如果重载逻辑需要复用，外部重载函数或类实现更值得推荐。
理解 TypeScript 类型兼容性在对象字面量方法重载中的检查机制后，再遇到“签名不兼容”错误就能快速定位问题：优先检查返回值是否比每个重载签名更具体，再看参数是否足够宽泛。方法位置的双变规则虽然比函数属性宽松，但重载检查依然要求实现函数覆盖所有调用签名。设计重载方法时，尽量让返回类型保持一致或存在清晰的父子关系，可以减少很多不必要的类型错误。
TypeScript类型兼容性对象字面量方法重载修改时间：2026-09-19 09:56:27