TypeScript递归映射类型多余属性报错漏检问题探究

问题复现 #

定义递归结构的对象类型时，最外层对象字面量的多余属性会正常触发类型报错，但嵌套层级内的同类型多余属性不会触发预期校验错误。
交叉类型写法复现：

type SomeType = {
  [P in 'u']?: string;
} & {
  [P in 'a' | 'b' | 'c' | 'd']?: SomeType;
}

const st: SomeType = {
  u: '1',
  a: {
    u: '2',
    b: {
      u: '3',
      c: {
        d: {},
        e: 1, // 未触发预期报错
      }
    },
  },
  e: 1, // 正常触发报错：对象字面量仅允许指定已知属性，"e"不存在于SomeType类型中
};

去掉交叉类型、直接显式定义所有可选属性，问题依然存在：

type SomeType = {
  u?: string;
  a?: SomeType;
  b?: SomeType;
  c?: SomeType;
  d?: SomeType;
}

const st: SomeType = {
  u: '1',
  a: {
    u: '2',
    b: {
      u: '3',
      c: {
        d: {},
        e: 1, // 未触发预期报错
      }
    },
  },
  e: 1, // 正常触发报错
};

核心原因 #

该行为是TypeScript为平衡校验性能与类型安全做的设计折中，并非bug：

• 多余属性检查（Excess Property Checking, EPC） 不是TypeScript结构类型系统的通用兼容规则，仅针对「对象字面量直接赋值给明确标注类型的位置」场景生效，本身存在明确的适用边界。
• 当递归类型的所有属性均为可选时，空对象{}会被判定为完全符合该类型要求。TypeScript做递归类型嵌套校验时，为避免无限递归引发性能问题、检查死循环，会在嵌套层级达到阈值、或匹配到“空对象合法”分支时放宽校验规则：只要嵌套对象能匹配部分合法结构，就不会对额外属性执行严格EPC校验，这是嵌套层e: 1不报错的根本原因。
• 交叉类型拆分属性、平铺定义可选属性两种写法，本质都生成了「全属性可选的递归对象类型」，都会触发上述校验兜底逻辑。

修复方案 #

将类型改写为单映射类型+条件判断形式，强制TypeScript遍历属性时明确每个键对应的类型，不触发递归校验的放宽逻辑，即可实现全层级的多余属性检查：

type P = 'u';
type Q = 'a' | 'b' | 'c' | 'd';

type SomeType = {
  [K in (P | Q)]?: K extends P
    ? string
    : SomeType
};

const st: SomeType = {
  u: '1',
  a: {
    u: '2',
    b: {
      u: '3',
      c: {
        d: {},
        e: 1, // 正常触发报错
      }
    },
  },
  e: 1, // 正常触发报错
};

内容的提问来源于stack exchange，提问作者Page not found