TypeScript索引签名困惑：类实现接口为何报错？

问题场景 #

当尝试通过带数字索引签名的Units接口约束Unit类时，类定义和内部的this[x]访问都会触发TypeScript错误：

Class 'Unit' incorrectly implements interface 'Units'. Index signature for type 'number' is missing in type 'Unit'.ts(2420)
Element implicitly has an 'any' type because expression of type 'number' can't be used to index type 'Unit'. No index signature with a parameter of type 'number' was found on type 'Unit'.ts(7053)

将索引签名直接写入类定义后，错误完全消失。相关代码示例如下：

interface Units {
  [key: number]: object;
}

// 错误写法（仅通过接口声明索引签名）
class Unit implements Units {
  constructor() {
    for(let x=1; x<=9; x++) {
      this[x] = {}; // 触发类型错误
    }
  }
}

// 正确写法（类显式声明索引签名）
class Unit implements Units {
  [key: number]: object;
  constructor() {
    for(let x=1; x<=9; x++) {
      this[x] = {}; // 无类型错误
    }
  }
}

核心原因解析 #

1. 接口与类的类型契约边界 #

TypeScript中，接口仅定义类需要对外暴露的结构契约，但不会自动将接口的成员（包括索引签名）“注入”到类的内部类型定义中。类必须显式声明自身的所有类型成员，才能让TypeScript确认类的内部操作（比如this访问）符合类型约束。

2. 数字索引签名的类型严格性 #

JavaScript底层中，对象的键本质都是字符串，但TypeScript的类型系统会严格区分number和string类型的索引。如果类仅通过接口声明数字索引签名，TypeScript无法确认类本身支持用数字类型的键进行访问/赋值，因此内部访问this[x]（x为number类型）时，会触发“无法用数字索引类型”的错误。

3. 显式声明索引签名的必要性 #

在类中显式写入[key: number]: object，相当于直接告诉TypeScript：该类本身支持以数字作为键来访问和赋值成员。这既满足了接口的外部契约要求，也解决了类内部this访问的类型推断问题，让TypeScript能够正确识别this[x]的类型合法性。

总结 #

接口的索引签名是类需要满足的外部行为规范，但类的内部类型系统需要显式的索引签名声明，才能完成内部操作的类型校验和接口契约的匹配。两者的作用边界不同，不能仅通过接口来替代类自身的索引签名声明。

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