TypeScript中已赋值为确定对象的静态属性为何报可能为undefined错误

问题场景 #

三个拆分在独立文件中的类代码在编译时触发类型错误，具体实现如下：

• DirectoryContents.ts

export class DirectoryContents
{
    public readonly directories: ReadonlyArray<string>;
    public readonly files: ReadonlyArray<string>;

    public constructor(directories: ReadonlyArray<string>, files: ReadonlyArray<string>)
    {
        this.directories = directories;
        this.files = files;
    }
}

• RootDirStructure.ts

import { DirectoryContents } from "./DirectoryContents";
import ReadOnlyDict = NodeJS.ReadOnlyDict;

export class RootDirStructure
{
    private static readonly REQUIRED_NPM_DIRECTORIES: ReadonlyArray<string> = ["node_modules"];
    private static readonly REQUIRED_NPM_FILES: ReadonlyArray<string> = ["package.json", "package-lock.json"];

    // 定义时已为required静态属性赋值确定的实例
    public static readonly required: ReadOnlyDict<DirectoryContents> = {
        npm: new DirectoryContents(
            RootDirStructure.REQUIRED_NPM_DIRECTORIES,
            RootDirStructure.REQUIRED_NPM_FILES
        )
    }
}

• Index.ts

import { RootDirStructure } from "./RootDirStructure";

class Index
{
    // 以下访问语句触发编译报错
    const requiredNPMDirectories: ReadonlyArray<string> = RootDirStructure.required.npm.directories;
}

核心疑问 #

RootDirStructure.required 静态属性已经在类定义阶段被显式赋值为确定存在的对象，对应值在编译阶段即可被追踪识别，跨文件访问RootDirStructure.required.npm.directories时，编译器仍然判定被访问对象可能为undefined，未识别到属性已被定义。

报错和静态属性的初始化时机、跨文件模块解析没有关系，核心原因是使用的NodeJS.ReadOnlyDict的类型定义规则：
该类型的内置索引签名为{ readonly [key: string]: T | undefined }，即通过任意字符串键访问字典属性时，返回值的类型是T | undefined的联合类型。哪怕实际赋值时已经传入了npm键值对，编译器也不会基于实际赋值内容收窄索引签名的返回类型，只要是通过索引方式访问的属性，都会默认带上可能为undefined的判定。
也就是说，required.npm 的类型是DirectoryContents | undefined，对这个值继续访问.directories属性时，自然就会触发“对象可能为undefined”的类型检查错误。

可落地的解决方案 #

• 替换字典类型为明确的结构类型，取消自带undefined的索引签名：

public static readonly required: { npm: DirectoryContents } = {
    npm: new DirectoryContents(/* 原有参数保持不变 */)
}

这种定义方式下required.npm 会被识别为确定存在的DirectoryContents实例，不会触发空值检查报错。

• 如果必须保留ReadOnlyDict 类型，可以在访问时添加空值保护：
  1. 非空断言写法（适合配置值100%存在的场景）：

     const requiredNPMDirectories = RootDirStructure.required.npm!.directories;
     

  2. 显式类型守卫写法（适合运行时需要兜底校验的场景）：

     const npmConfig = RootDirStructure.required.npm;
     if (!npmConfig) throw new Error("npm目录结构配置缺失");
     const requiredNPMDirectories = npmConfig.directories;
     

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