TypeScript noUncheckedIndexedAccess 开启后的数组读取处理方案

开启 noUncheckedIndexedAccess 后，TypeScript 会把没有被证明存在的数组下标读取视为“可能是 undefined”。最实用的处理顺序是：不需要下标就使用 for...of，需要下标就先做边界判断，确实允许缺省时使用默认值，只有已经建立不变量时才使用非空断言。

官方文档：https://www.typescriptlang.org/tsconfig/noUncheckedIndexedAccess.html

开启后到底改变了哪一种数组读取

TypeScript 4.1 引入了 --noUncheckedIndexedAccess。它针对的是索引签名和下标访问的“乐观假设”：编译器不再默认任意键或任意下标一定对应一个值。

interface User {
  id: string;
  name: string;
}

function firstName(users: User[]) {
  // 开启 noUncheckedIndexedAccess 后，users[0] 的类型是 User | undefined。
  const first = users[0];
  return first?.name ?? "暂无用户";
}

这里的关键不是数组本身变成了“可选数组”，而是 users[0] 这个访问动作没有证明下标 0 一定落在有效范围内。因此，固定属性 user.name 仍然是 string，动态索引和数组下标才需要额外处理。

不需要下标时优先使用 for-of

很多报错来自一个并不需要索引的循环。代码只想逐个读取字符串、渲染列表或调用对象方法时，让循环变量直接代表元素即可。

function printNames(names: string[]) {
  // for-of 直接取得已存在的元素，不引入额外的下标读取。
  for (const name of names) {
    console.log(name.toUpperCase());
  }

  // forEach 的回调参数同样被推断为 string。
  names.forEach((name) => {
    console.log(name.trim());
  });
}

如果还需要序号，可以把索引当作附加信息，而不要把它重新用于读取同一个数组。例如使用 names.entries() 获取索引和元素的配对；在现代目标配置下，元素变量仍然是直接从迭代器得到的 string。

必须保留下标时怎样安全收窄

需要把当前元素和前后元素比较、同步渲染位置或写回同一个下标时，下标访问是合理的。这时要把“下标一定有效”的条件写在代码里。

function pairWithNext(values: string[]): string[] {
  const pairs: string[] = [];

  for (let index = 0; index  ${next}`);
    }
  }

  return pairs;
}

即使循环条件已经限制了数字范围，TypeScript 对普通数组也不会自动把两个索引都收窄成元素类型；显式判断是最容易读懂、也最能抵抗后续代码改动的写法。若读取本来就可以缺失，可以用空值合并提供业务默认值：

function labelAt(labels: string[], index: number): string {
  // 越界时使用可见的占位文本，而不是把 undefined 传给界面。
  return labels[index] ?? "未命名";
}

非空断言什么时候才值得使用

values[index]! 会告诉编译器“这里一定存在”，但它不会在运行时增加任何边界检查。只有调用方已经建立了不可为空的不变量时，断言才有意义，例如先判断数组非空，再把第一个元素交给只接受元素类型的函数。

function requireFirst(values: string[]): string {
  if (values.length === 0) {
    throw new Error("至少需要一个值");
  }

  // 前面的分支建立了非空数组不变量，此处断言只是在类型上表达该事实。
  return values[0]!;
}

如果这个不变量来自远端接口、用户输入或可变共享状态，优先返回 string | undefined、抛出明确错误或使用默认值。不要为了让编译器安静而在所有下标后面机械追加 !，那会把配置带来的边界提示重新变成运行时风险。

怎样把这个选项纳入项目迁移

noUncheckedIndexedAccess 不会随 strict 自动开启，官方说明是因为大型代码库可能遇到较多迁移噪声。比较稳妥的做法是先在一组数组和字典访问集中的目录启用，再按访问意图修复，而不是全局批量加断言。

常见问题

为什么写了 index 还会报错？

数组长度是运行时可变属性，TypeScript 不会把普通数字索引自动证明成一定存在。保留索引时，再对读取结果做显式判断，或把已建立的不变量用局部断言表达出来。

是不是应该关闭 noUncheckedIndexedAccess？

不必因为迁移报错就马上关闭。先区分“本来不需要下标”和“确实需要处理越界”两类代码；只有团队明确不接受迁移成本时，才评估暂缓启用。

什么时候可以直接使用数组下标后的感叹号？

只有在同一段逻辑中已经检查非空、索引来自受约束的集合，或函数契约明确保证元素存在时才适合。否则应让 undefined 继续向调用方传递并被处理。