TypeScript索引签名全解析：从动态属性建模到类型安全实战

1. 一个让 TypeScript 开发者又爱又恨的语法

如果你写过一段时间的 TypeScript，大概率碰到过这种报错：Element implicitly has an 'any' type because expression of type 'string' can't be used to index type。刚看到这个错误的时候，我第一反应是"TS 怎么这么烦"，后来才意识到，这是我压根没搞懂索引签名（Index Signature）到底在做什么。

说句实话，索引签名是 TypeScript 里非常特别的一个设计。它不像泛型、条件类型那样需要绕脑子，但它在实际项目里出现的频率极高——表单校验、字典映射、枚举反查、配置项合并、接口返回数据扁平化，几乎每个场景都离不开它。可恰恰是这样一个高频语法，翻车几率也高得离谱。我见过不少项目里，为了绕过索引签名报错，直接写 as any，然后把类型安全的底裤脱了个精光。也见过有人不管三七二十一，给所有 interface 都加一个 [key: string]: any，结果类型检查形同虚设，等于回到 JavaScript 的怀抱。

这篇文章正本清源，把索引签名从头到尾拆一遍。我会从它的本质原理讲起，然后是各种写法和适用场景，再带你看它和 Record、Map 之间怎么选，最后结合一些真实项目里的高阶玩法，把坑和经验都摊开讲。不管你是刚学 TS 的新手，还是写了两年 TS 但一直被类型体操折磨的老手，这篇文章都能帮你把索引签名这块拼图补齐。

2. 索引签名的本质：给 TypeScript 一个"动态属性"的合约

2.1 为什么需要索引签名

要理解索引签名，得先从 TypeScript 类型系统的"静态"特性说起。TypeScript 的核心工作是在编译期确定对象有哪些属性、每个属性是什么类型。这在属性固定的场景下非常好用——你定义了一个 interface User { name: string; age: number }，那么 TS 就能明确告诉你 user.name 是字符串，user.age 是数字，写错了马上能发现。

但真实项目里，对象的属性往往不是写死的。典型的例子：

typescript复制// 这是一个 form 的错误信息收集器
const formErrors: Record<string, string> = {};

// 用户填完一个字段，我们就把错误信息塞进去
formErrors['email'] = '邮箱格式不正确';
formErrors['phone'] = '手机号不能为空';

formErrors 的 key 在写代码的时候根本无法穷举，用户可能提交一百个字段，也可能只提交三个字段。如果按固定属性的 interface 来定义，你得把每个可能的字段都列出来——这既不现实，也不可维护。

再比如接口返回的数据：

typescript复制// 后端返回：记录每个用户的积分
const scoreMap = {
  'u_1001': 95,
  'u_1002': 87,
  'u_1003': 76,
};

用户 ID 随时可能增加，你不可能预先把所有用户 ID 写成类型。这时候就需要一个机制，让 TypeScript 知道："这个对象允许你用字符串去索引它，索引到的值类型是 number"。这个机制，就是索引签名。

2.2 索引签名的语法拆解

索引签名的写法非常简洁，就一行：

typescript复制interface ScoreMap {
  [key: string]: number;
}

方括号里的 [key: string] 表示"这个接口允许通过 string 类型的 key 来索引"，冒号后面的 number 表示"索引到的值的类型是 number"。key 这个名字是可以随便起的，它只是一个形式参数名，就像函数参数一样，叫 key 可以，叫 id 也可以，但社区约定俗成叫 key，可读性最好。

• [key: string]: key 的类型必须是 string。注意这里说的是"key 的类型"，不是"key 的取值"。也就是说，任何字符串都可以作为这个对象的属性名。
• : number: 这个对象的所有属性值都必须是 number 类型。
• 要支持其他类型的 key，TS 还提供了数字签名 [key: number] 和符号签名 [key: symbol]。但通常来说，用得最多的就是字符串索引签名。

写完之后，你就可以用字符串动态访问对象：

typescript复制const scores: ScoreMap = {
  'u_1001': 95,
  'u_1002': 87,
};

scores['u_1003'] = 76;          // ok，u_1003 是合法字符串 key
scores['new_user'] = 100;       // 也 ok，TS 不关心具体是什么字符串

2.3 类型检查的核心逻辑：不是限制 key，而是约束 value

很多人对索引签名有误解，以为它是"白名单机制"，会限制对象只能有规定好的 key。恰恰相反，索引签名是一种"通配声明"——它告诉 TypeScript："所有字符串命中的属性，类型都是 number"，它限制的是"这个对象上的一切字符串属性，值都必须是 number"。

这个区分很重要。看个例子：

typescript复制interface StringDictionary {
  [key: string]: string;
}

const dict: StringDictionary = {
  name: '张三',
  // age: 30,  // 报错！类型 number 不能赋值给类型 string
};

name: '张三' 之所以合法，不全因为它是固定属性，而是因为 '张三' 是 string，符合索引签名的约束。反过来，如果你想塞一个 age: 30 进去，TS 会用索引签名去检查：age 这个字符串属性命中了 [key: string]: string，那它的值必须是 string，可 30 是 number，于是报错。

一个核心推论：如果 interface 里声明了索引签名，那所有显式声明的固定属性，它们的类型必须能被索引签名的值类型接收。也就是说，要么类型相同，要么固定属性类型是索引签名值类型的子类型。

typescript复制// 正确写法：固定属性 age 的类型 number，可以被 string 索引签名的值类型 string|number 接收
interface MixedDictionary {
  [key: string]: string | number;
  age: number;      // number 是 string|number 的子类型，合法
  name: string;     // string 也是 string|number 的子类型，合法
}

// 错误写法：
// interface BadDictionary {
//   [key: string]: string;
//   age: number;    // number 无法赋值给 string，报错
// }

如果你需要"一部分属性是 string，其他动态属性是 number"，传统索引签名行不通，因为所有字符串属性（包括显式定义的）都等于索引签名的属性，它们的值不能互相矛盾。

这是理解索引签名最核心的一条规则，后面很多坑都从这里冒出来。

3. 从原始类型到字面量：索引签名 key 的类型进阶

3.1 为什么 key 的类型可以是 string、number 或 symbol，但不能是 boolean 或对象

TypeScript 索引签名的 key 类型被限制为 string、number 和 symbol。为什么？

因为 JavaScript 对象的键，本质上是三种：字符串、数字、Symbol。你把一个对象传进去当 key，JS 引擎会悄悄调用它的 toString() 方法转成字符串。正因为做了隐式转换，TS 认为这种"转成字符串后用字符串索引"的操作不够安全，干脆直接禁止对象、数组、boolean 等当索引签名的 key 类型。

数字作为 key 时更微妙。JS 的属性名其实都是字符串，"0" 和 0 访问的是同一个属性。TS 对此睁一只眼闭一只眼，但严格来说，数字索引签名定义的是"数值型属性名"的访问方式。

typescript复制interface NumericDictionary {
  [index: number]: string;
}

const arr: NumericDictionary = ['a', 'b', 'c'];

arr[0]    // 类型为 string
arr[1]    // 类型为 string

这个数组就是通过数字索引签名约束的——每一项的值是 string。当你定义一个数组类型 string[]，TS 本质上也是在应用数字索引签名。

3.2 联合类型作为索引签名 key：有限字典的高级玩法

string、number、symbol 是索引签名 key 的全部吗？别忘了，TS 支持字面量类型，所以 key 也可以是"特定的字符串字面量的联合"。但这种写法，官方并不通过索引签名语法支持，而是通过 in 操作符，在映射类型（Mapped Type）里实现的。

typescript复制type Permission = 'read' | 'write' | 'delete';

// 这会导致一个对象，三个 key 都必须存在
type PermissionMap = {
  [key in Permission]: boolean;
};

const permissions: PermissionMap = {
  read: true,
  write: false,
  delete: true,
};

这是映射类型（Mapped Type），不是索引签名。它们的区别在于：索引签名是"任意 string 都行，不管你有没有声明"，映射类型是"必须包含这些特定的 key，一个都不能少，也不能多"。前者常用于动态字典，后者常用于枚举映射、权限表等 key 集合确定的场景。

很多人分不清 [key: string]: boolean 和 [key in 'read' | 'write' | 'delete']: boolean，以为都能用来当"对象 key 集合"，其实差异很大。一个最直观的对比：

typescript复制// 索引签名：key 集合开放
interface OpenMap {
  [key: string]: boolean;
}
const openMap: OpenMap = {};   // 合法：空对象没有任何字符串属性，但没有违反规则

// 映射类型：key 集合封闭
type PermissionMap = {
  [key in Permission]: boolean;
};
//