TypeScript模块扩展中如何扩展嵌套属性？

问题核心 #

你遇到的问题根源是：错误地重写了整个嵌套对象而非增量扩展子接口，导致顶层属性扩展生效，但嵌套的子接口属性扩展不生效。

原始文件示例 #

先看你的基础定义文件animal.types.d.ts：

// animal.types.d.ts
export interface Animal {
  topLevelProperty: string;
  Schemas: {
    Dog: {
      age: number;
    };
    Cat: {
      breed: string;
    };
  };
}

错误的扩展写法（导致嵌套属性不生效） #

如果直接在顶层Animal接口里重新定义Schemas，会覆盖原有嵌套类型，导致扩展的name属性不生效：

// augment-animal.d.ts（错误写法）
import { Animal } from './animal.types';

declare module './animal.types' {
  interface Animal {
    topLevelProperty: number; // 顶层扩展生效
    Schemas: {
      Dog: {
        name: string; // 此扩展不生效，因为重新定义了整个Schemas
      };
    };
  }
}

正确的扩展写法 #

要单独对嵌套的子接口做增量扩展，直接定位到Animal['Schemas']进行扩展：

// augment-animal.d.ts（正确写法）
import { Animal } from './animal.types';

declare module './animal.types' {
  // 扩展顶层属性（按需）
  interface Animal {
    topLevelProperty: number;
  }

  // 增量扩展嵌套的Schemas子接口中的Dog类型
  interface Animal['Schemas'] {
    Dog: {
      name: string;
    };
  }
}

验证使用（usage.ts） #

此时在usage.ts中使用扩展后的类型不会报错：

// usage.ts
import './augment-animal';
import { Animal } from './animal.types';

const dog: Animal['Schemas']['Dog'] = {
  age: 3,
  name: '旺财' // 正常识别，无报错
};

关键注意事项 #

• 确保扩展文件是模块：文件中必须包含import/export语句，否则TypeScript会将其视为全局声明，无法正确关联到目标模块的接口扩展。
• 增量扩展原则：TypeScript接口扩展是增量式的，直接修改子接口而非重写父级嵌套对象，才能保留原有属性并添加新属性。

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