TypeScript联合类型校验通过但不匹配任意成员，如何避免该问题？

TS 联合类型默认采用「鸭子类型」校验规则，只要值满足联合中任意一个成员的最小属性要求就会校验通过，多余属性只要存在于联合的其他成员定义中就不会触发报错，这是官方明确的设计特性。要实现完全匹配联合成员、禁止跨成员多余属性的效果，可通过泛型工具类型实现：

核心工具类型定义 #

// 严格联合类型工具：要求值必须完全匹配联合中的某一个成员，禁止出现其他成员的独有属性
type StrictUnionHelper<T, TAll> = 
  T extends any ? T & Partial<Record<Exclude<keyof TAll, keyof T>, never>> : never
type StrictUnion<T> = StrictUnionHelper<T, T>

测试场景改造效果 #

将需要严格校验的联合类型用StrictUnion包裹即可：

type A = Partial<{ 
  foo: number
  bar: string
}>

type B = Partial<{
  foo: number
  other: string
}>

type C = A & B & { $inherit: "b" }

// 用StrictUnion包裹后实现严格校验
type StrictAC = StrictUnion<A | C>

// 此处会正常触发类型报错：既不满足A的要求（存在多余属性other），也不满足C的要求（缺少必填$inherit属性）
const c: StrictAC = {
  foo: 3,
  other: 'cool',
}

React 组件注入属性场景适配 #

针对你要实现的带$前缀扩展属性的模块化React组件，可按如下方案实现类型安全：

import React from 'react'

// 1. 定义组件原生Props
type FooNativeProps = {
  children?: React.ReactNode
  // 其他组件原生属性...
}

// 2. 定义$inherit配置与对应扩展属性的映射
type InheritConfigMap = {
  border: {
    $borderColor?: string
    $borderWidth?: number
  }
  // 可扩展其他inherit配置
}

// 3. 生成所有扩展Props的联合
type InheritProps<K extends keyof InheritConfigMap = keyof InheritConfigMap> = 
  K extends keyof InheritConfigMap 
    ? { $inherit: K } & InheritConfigMap[K] & Record<`$${string}`, any>
    : never

// 4. 组件最终Props = 严格联合的 原生Props | 扩展Props
type FooComponentProps = StrictUnion<FooNativeProps | InheritProps>

// 5. 组件实现
const FooComponent: React.FC<FooComponentProps> = (props) => {
  // 内部逻辑处理扩展属性
  return <div {...props} />
}

// 测试效果
// ✅ 合法：原生用法
<FooComponent />
// ✅ 合法：带$inherit配置的扩展用法
<FooComponent
  $foo="bar"
  $inherit="border"
  $borderColor="red"
/>
// ❌ 报错：存在$borderColor属性，但未声明对应的$inherit="border"配置
<FooComponent $borderColor="red" />

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