TypeScript不允许React组件Props使用合法联合类型的问题排查

问题原因 #

你遇到的问题本质是TypeScript对带可选never属性的排他联合类型的类型拓宽行为：当传递对象字面量作为props时，TS会自动将可选属性的类型拓宽为原类型 | undefined，而undefined无法赋值给never类型，导致类型检查报错。即使传递的props完全匹配联合分支，TS也会因为拓宽后的类型不符合never约束而报错。

解决方案（不牺牲类型明确性） #

1. 简化联合类型定义，利用判别式自动排他 #

不需要prop?: never的技巧，直接用判别式联合（这里version就是天然的判别式），TS会自动根据判别式收窄类型，同时在外部传递时严格检查属性的排他性：

// 组件Props定义
type Props = 
  | { version: 'v1', onlyOnV1: string }
  | { version: 'v2', onlyOnV2: number };

// 组件实现
const MyComponent = (props: Props) => {
  const { version } = props;
  if (version === 'v1') {
    // TS自动收窄为v1分支，onlyOnV1可安全访问
    return <div>{props.onlyOnV1}</div>;
  }
  // TS自动收窄为v2分支，onlyOnV2可安全访问
  return <div>{props.onlyOnV2}</div>;
};

// 父组件使用（无类型错误）
<MyComponent version="v1" onlyOnV1="v1专属内容" />
<MyComponent version="v2" onlyOnV2={123} />
// 错误示例：传递不属于当前version的属性会直接报错
<MyComponent version="v1" onlyOnV2={123} /> // TS报错：类型不兼容

这种方式既保留了类型明确性，又避免了never带来的类型拓宽问题，是最推荐的方案。

2. 保留never写法时，用as const避免类型拓宽 #

如果因为某些原因必须保留never属性的定义，可以通过as const强制TS将对象字面量视为字面量类型，避免自动拓宽：

// 原Props定义
type Props = 
  | { version: 'v1', onlyOnV1: string; onlyOnV2?: never }
  | { version: 'v2', onlyOnV2: number; onlyOnV1?: never };

// 父组件使用时，用as const约束类型
<MyComponent {...({ version: 'v1' as const, onlyOnV1: 'test' })} />

// 或者先定义const变量再传递
const v1Props = { version: 'v1' as const, onlyOnV1: 'test' };
<MyComponent {...v1Props} />

3. 用交叉+条件类型实现严格排他联合 #

如果需要更严格的类型约束，可以用交叉类型和Omit实现完全排他的联合，确保每个分支只包含自己的专属属性：

type BaseProps = { version: 'v1' | 'v2' };
type V1Specific = { onlyOnV1: string };
type V2Specific = { onlyOnV2: number };

// 生成严格排他的联合类型
type Props = 
  | (BaseProps & { version: 'v1' } & V1Specific & Omit<V2Specific, never>)
  | (BaseProps & { version: 'v2' } & V2Specific & Omit<V1Specific, never>);

这种方式的效果和判别式联合一致，但写法更繁琐，适合复杂场景。

总结 #

你没有错误使用联合类型，但prop?: never的技巧在对象字面量传递时会触发TS的类型拓宽，导致报错。通过简化联合类型定义（利用判别式）或用as const避免类型拓宽，可以在完全保留类型明确性的前提下解决问题。

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