TypeScript 怎样让索引访问显式处理 undefined

TypeScript 默认把很多动态索引读取当成“值一定存在”。这对固定对象属性很方便，但对数组越界、环境变量和服务端字典并不安全。打开 noUncheckedIndexedAccess 后，未声明的索引结果会显式变成目标类型与 undefined 的联合类型，调用方必须先决定缺失时怎么办。

开启 noUncheckedIndexedAccess，先看清类型变化

在项目的 tsconfig.json 中加入下面的配置。它通常与 strict 一起使用，但开关本身只改变索引访问的类型推断。

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

例如，EnvironmentVars 明确声明了 NAME，因此 env.NAME 仍然是 string；而通过索引签名访问的 env["NODE_ENV"] 会变成 string | undefined。这正好对应运行时“键可能不存在”的事实。

interface EnvironmentVars {
  NAME: string;
  [key: string]: string;
}

declare const env: EnvironmentVars;
const appName = env.NAME; // 已声明属性，类型仍是 string
const nodeEnv = env["NODE_ENV"]; // 动态索引，类型是 string | undefined

// 先判断缺失情况，再把值交给只接受 string 的函数
const normalizedEnv = nodeEnv ?? "development";
console.log(normalizedEnv.toLowerCase());

数组下标要做存在性收窄

数组也是索引访问。users[0] 在空数组上会得到 undefined，所以不能因为数组元素类型写成 User，就假设下标一定有效。

type User = { id: string; name: string };

function firstUserName(users: User[]): string {
  const first = users[0];
  // 下标可能越界，先收窄再读取属性
  if (first === undefined) {
    return "暂无用户";
  }
  return first.name;
}

function printUsers(users: User[]): void {
  // for...of 直接遍历实际元素，不需要手动处理下标空洞
  for (const user of users) {
    console.log(`${user.id}: ${user.name}`);
  }
}

如果业务允许空数组，显式返回“暂无用户”或抛出领域错误比写 users[0]! 更可靠。只有在上游已经用长度检查或固定元组证明下标存在时，非空断言才有合理边界。

用 keyof 和边界函数收拢动态读取

当键集合是已知的，不要把所有对象都写成宽泛的 Record。用 keyof 约束调用方，能让拼写错误在编译期暴露；当键来自外部请求时，再在边界函数中返回可处理的联合类型。

type FeatureFlags = {
  checkout: boolean;
  search: boolean;
};

function readFlag(flags: FeatureFlags, key: keyof FeatureFlags): boolean {
  // keyof 保证 key 属于已声明集合，结果可以安全返回 boolean
  return flags[key];
}

function readExternalFlag(
  flags: Record,
  key: string,
): boolean {
  // 外部键可能不存在，用明确默认值封装不确定性
  return flags[key] ?? false;
}

这两个函数表达的是不同契约：readFlag 接受内部已知键，调用错误应当尽早失败；readExternalFlag 面对接口或配置输入，缺失值有明确的安全默认值。不要用同一个宽泛类型覆盖两种场景。

配置默认值、异常和非空断言怎么选

最后检查三处容易漏改的位置：数组的 map 前手写下标读取、字典读取后立即调用方法、以及把动态键转成固定类型的类型断言。启用该选项的目的不是让错误变多，而是把“值可能不存在”的运行时事实推到最靠近使用点的位置。

常见问题

开启后，所有对象属性都会变成 undefined 联合类型吗？

不会。类型中明确声明存在的属性保持原类型，主要变化是未声明的索引访问和可能越界的数组下标。

可以直接把索引结果写成非空断言吗？

可以，但只适合前面已经有可靠证明的局部代码。对外部输入、环境变量和数组首项，优先使用判断、默认值或错误处理。

为什么 for...of 通常比下标循环省事？

它直接取得数组中的实际元素，不需要为每个下标额外处理越界类型；需要索引位置时，再保留显式的长度边界检查。