索引签名在TypeScript中用于描述“对象可以拥有任意键”的场景，例如字典、缓存、配置映射等。它的写法很直观：interface StringMap { [key: string]: string }。但很多人在给这类类型赋值时，会突然收到类似“类型‘{ name: string; age: number; }’不可分配给类型‘StringMap’”的报错，即便这个对象的键确实都是字符串。出现这种现象的根本原因在于，TypeScript对索引签名执行的不是简单的结构匹配，而是基于赋值方向的显式兼容性验证。在开启strict模式后，这种验证会变得更加严格，尤其是当索引签名的值类型是联合类型或包含可选属性时。
理解这个机制，需要先区分两种不同的赋值场景。第一种是“变量赋值”：把一个对象字面量直接赋值给带索引签名的接口变量；第二种是“类型断言”：通过as或尖括号语法强制告诉编译器忽略可能的不兼容。TypeScript在这两种场景下采用的检查策略是不同的。对于前者，编译器会依次检查对象字面量中的每一个已知属性，确认它们的值类型是否能够赋值给索引签名定义的值类型。如果有一个属性不匹配，整个赋值就会失败。这种检查方式被称为“隐式索引签名检查”，它只在直接赋值对象字面量时触发，通过中间变量赋值则可能绕过部分检查。
索引签名的兼容性判定与值类型约束
索引签名的核心规则是：对象中所有已知属性的类型必须是索引签名值类型的子类型。例如，下面的代码会报错：
interface StringMap {
[key: string]: string;
}
const obj: StringMap = {
name: "Alice",
age: 30 // 错误：number 不能赋值给 string
};
这里age的值是number，而索引签名要求所有属性的值都是string，因此TypeScript会提示age属性不兼容。需要注意的是，即使name属性符合要求，编译器不会只检查不匹配的属性并忽略，而是整个对象字面量赋值失败。这意味着你无法在一个带字符串索引签名的接口中允许存在不同类型的属性，除非把值类型声明为联合类型或any。
当索引签名的值类型是联合类型时，检查依然严格，但允许每个属性是联合类型的任意成员。例如[key: string]: string | number，那么同时包含name: string和age: number的对象就能通过检查。不过，如果引入可选属性，情况会变得微妙。可选属性本质上是类型 | undefined，若索引签名值类型没有包含undefined，那么可选属性可能导致赋值失败。在关闭strictNullChecks时，undefined会被自动视为可分配给任何类型，因此不会报错；一旦开启，这个隐式规则消失，可选属性与索引签名之间的兼容性就完全取决于值类型是否显式包含undefined。
另一个容易被忽略的点是数字索引签名和字符串索引签名的关系。在JavaScript中，对象的数字键最终会被转换为字符串，因此TypeScript规定：如果同时声明了数字索引签名和字符串索引签名，那么数字索引签名的值类型必须是字符串索引签名值类型的子类型。例如：
interface MixedIndex {
[index: number]: string;
[key: string]: number | string;
}
上述代码会报错，因为数字索引签名的值类型是string，而字符串索引签名的值类型是number | string，string确实是子类型，所以实际上通过。反过来，如果数字索引签名的值类型是number | string而字符串索引签名是string，就会报错，因为number不是string的子类型。这个规则在strict模式下没有额外变化，但很多人会因为它出现在赋值错误的上下文中而产生误解。
strict模式放大了赋值场景中的检查差异
strict模式并不是一个单一的编译选项，它聚合了strictNullChecks、noImplicitAny、strictFunctionTypes等多个子选项。对于索引签名，影响最大的通常是strictNullChecks和noImplicitAny。前者改变了undefined和null的可赋值性，后者则会影响那些没有显式类型注解的函数的参数推断，从而间接影响通过函数返回对象字面量赋给索引签名类型的场景。
举例来说，在非严格模式下，下面这段代码是允许的：
interface Dictionary {
[key: string]: string;
}
function getConfig() {
return { key: "value", count: 1 };
}
const dict: Dictionary = getConfig(); // 非严格模式下不报错？实际上取决于noImplicitAny等
实际上，即使关闭strict，只要strictNullChecks是关闭的，count: 1是一个number，仍然不允许赋值给string类型的索引签名，因为number到string本身就不兼容，与null或undefined无关。所以这段代码在严格和非严格模式下都会报错。真正受到strict影响的是当对象属性的值类型为undefined或null时，或者索引签名值类型为联合类型但允许隐式包含undefined的情况。
一个更典型的strict相关例子是，在开启strictNullChecks之前，下面代码可以通过：
interface LooseIndex {
[key: string]: string;
}
const data: LooseIndex = {
name: "Tom",
nickname: undefined
};
因为undefined在非严格模式下可以被赋值给string。开启strictNullChecks后，编译器会提示undefined不能赋值给string，除非索引签名改为[key: string]: string | undefined。这就是很多旧项目在升级TypeScript并开启strict后突然出现大量索引签名赋值报错的原因。
此外，noImplicitAny会影响函数返回值推断为any的情况。如果一个函数没有显式返回类型，并且返回对象字面量，TypeScript通常能推断出具体类型。但如果函数内部使用了动态键或any类型的变量，返回类型可能被推断为{ [key: string]: any }，此时再赋值给带索引签名的接口时，检查会宽松很多，因为any可以赋值给任何类型，反之亦然。但一旦显式标注返回类型为具体接口，检查就会变得严格。这提醒我们：在strict模式下，尽量为公共API函数提供显式返回类型，可以减少因隐式推断导致的兼容性误判。
绕过严格检查的几种方式及其适用边界
当索引签名的严格检查阻碍了合理的代码设计时，开发者通常会采用类型断言、中间变量、或者修改索引签名值类型等方案。类型断言是最直接的方式，例如const dict = { age: 30 } as unknown as Dictionary。但使用as unknown as的双重断言会完全绕过编译器的类型检查，相当于放弃了索引签名本应提供的类型保障。更推荐的做法是使用中间变量：
interface Dictionary {
[key: string]: string;
}
const temp = { name: "Alice", age: 30 };
const dict: Dictionary = temp; // 错误依然存在
有趣的是，中间变量并不能绕过索引签名检查。TypeScript对变量赋值的检查同样会查看源类型的每个已知属性是否匹配目标索引签名。即使将对象字面量先存入变量，赋值时依然会触发相同的检查。所以中间变量只是改变了错误报告的位置，并没有改变检查逻辑。
真正有效的绕过方式包括：将索引签名值类型扩展为联合类型，例如[key: string]: string | number；或者使用交叉类型结合具体接口，让一个类型既有索引签名又有固定属性。例如：
type Config = {
name: string;
age: number;
} & {
[key: string]: string | number;
};
const config: Config = {
name: "Alice",
age: 30,
city: "Shanghai"
};
这种交叉类型的写法允许同时享受具体属性检查和索引签名的灵活性，但代价是索引签名必须包含所有可能出现的值类型。如果未来新增的属性类型超出了联合类型范围，仍然会报错，不过这也正是类型安全的意义所在。
另一种常见做法是使用Record工具类型替换索引签名。Record<string, string>在行为上与{ [key: string]: string }几乎一致，但它是一个泛型别名，在一些复杂类型推导中可能会产生不同的结果。例如把Record<string, string>赋值给{ [key: string]: string }通常没问题，反过来也可以。但Record无法表达数字索引签名与字符串索引签名之间的约束关系，因此当需要同时定义两种索引签名时，还是应该使用接口语法。
最后要强调的是，索引签名并不适合所有场景。如果对象的结构是已知且固定的，直接定义具体接口会比使用索引签名更安全、更易维护。索引签名应当只用于那些确实需要支持动态键的容器，比如配置映射、事件处理器注册表、或来自外部API的任意键值数据。当你在这些场景中遇到严格模式下的兼容性报错时，先检查索引签名的值类型是否合理，再考虑调整值类型或使用交叉类型，而不是急于用类型断言掩盖问题。
TypeScript索引签名类型兼容性修改时间：2026-09-20 20:15:03