[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 noUncheckedIndexedAccess, TypeScript 中的 strict

TypeScript 中的 noPropertyAccessFromIndexSignature

一句话定义

noPropertyAccessFromIndexSignature 要求：如果一个属性其实来自索引签名，就必须用方括号访问，而不是点语法。

核心机制 / 工作原理

官方文档说明，这个选项的目标是保持访问语法和类型声明之间的一致性。

例如：

interface GameSettings {
  speed: "fast" | "medium" | "slow";
  quality: "high" | "low";
  [key: string]: string;
}

默认情况下，TypeScript 允许你写：

settings.username;

即使 username 并不是显式声明的属性，而只是被索引签名兜底。

开启：

{
  "compilerOptions": {
    "noPropertyAccessFromIndexSignature": true
  }
}

后，官方文档说明这会报错，并要求你改成：

settings["username"];

最小例子 / 最小场景

它最适合以下对象：

• 配置字典
• 任意键 map
• 环境变量对象

这些对象里，“我确定这个字段是已声明属性” 和 “我只是通过索引去试探一个键” 本来就不是一回事。

边界与易混淆点

它不是禁止索引签名

它并不阻止你写：

• [key: string]: T

它只是要求：

• 访问这些不确定字段时，语法也要显式表达这种不确定性

它和 noUncheckedIndexedAccess 关心的是同一风险域，但角度不同

• noPropertyAccessFromIndexSignature 更强调访问语法的意图
• noUncheckedIndexedAccess 更强调访问结果可能为 undefined

它不一定是 strict 的同义项

很多团队会把它当作额外强化字典访问纪律的开关，而不是默认所有项目都开。

参考信息

• TSConfig noPropertyAccessFromIndexSignature: https://www.typescriptlang.org/tsconfig/noPropertyAccessFromIndexSignature.html