[!info] related notes

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

TypeScript 中的 noUncheckedIndexedAccess

一句话定义

noUncheckedIndexedAccess 会把索引签名下那些“没有被显式声明过的属性访问”自动加上 undefined。

核心机制 / 工作原理

官方文档举的典型例子是：

interface EnvironmentVars {
  NAME: string;
  OS: string;
  [propName: string]: string;
}

默认情况下：

env.NODE_ENV

会被当成：

• string

因为索引签名说“任意字符串键都映射到 string”。

而开启：

{
  "compilerOptions": {
    "noUncheckedIndexedAccess": true
  }
}

后，官方文档明确说明：

• TypeScript 会给未声明字段加上 undefined

于是：

env.NODE_ENV

就会变成：

• string | undefined

最小例子 / 最小场景

这在以下场景尤其有价值：

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

边界与易混淆点

它主要影响“索引访问的安全感”

这个选项不是在说对象整体有问题，而是在提醒：

• 通过宽泛索引签名访问出来的值，不一定真存在

它常被当成额外严格性开关

很多项目会把它看成：

• 比默认 strict 更进一步的索引访问安全约束

它特别适合那些不想轻易把字典访问结果当作一定存在的项目。

它不会替代运行时判空

即使类型里已经变成 string | undefined，真正访问前还是要在代码里做显式处理。

参考信息

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