使用条件类型时TypeScript未对缺失组件属性发出警告

核心问题场景 #

你需要实现一个React组件：

• 传入href时渲染<a>标签，且hrefLang为必填项
• 不传入href时渲染<button>标签
  使用条件类型定义Props后，传入<Hybrid href="/asd">Button 1</Hybrid>时TypeScript未检测到缺失hrefLang的错误，但函数重载方案能正常触发校验。

条件类型方案失效的常见原因 #

1. 联合类型分支未明确禁止href属性 #

如果你的条件类型最终生成的是如下联合类型，会导致校验失效：

type HybridProps = 
  | { href: string; hrefLang: string; children: React.ReactNode }
  | { children: React.ReactNode }; // 未禁止href属性

原因：TypeScript的结构类型系统允许对象拥有额外属性。当你传入带href但缺hrefLang的props时，TypeScript会认为它可以匹配第二个分支（该分支没有限制href的存在），从而绕过hrefLang的必填校验。

正确的联合类型写法需要明确禁止非href分支的href属性：

type HybridProps = 
  | { href: string; hrefLang: string; children: React.ReactNode }
  | { href?: never; children: React.ReactNode }; // 禁止href存在

2. 泛型条件类型的推断局限性 #

如果你的方案使用了泛型条件类型，但未将泛型参数与href属性直接绑定，例如：

type HybridProps<T = unknown> = T extends { href: string } 
  ? { href: string; hrefLang: string; children: React.ReactNode }
  : { children: React.ReactNode };

const Hybrid = <T>(props: HybridProps<T>) => { /* 渲染逻辑 */ };

原因：TypeScript无法自动根据传入的props推断T的类型——T是独立的泛型参数，未与props的href属性建立直接关联。此时传入带href的props时，TypeScript无法正确推导泛型类型，导致条件类型的约束失效。

3. 函数重载有效的原因 #

函数重载的匹配逻辑更直接：

function Hybrid(props: { href: string; hrefLang: string; children: React.ReactNode }): JSX.Element;
function Hybrid(props: { children: React.ReactNode }): JSX.Element;
function Hybrid(props: any) {
  // 渲染逻辑
}

TypeScript会按照重载的定义顺序匹配参数类型：

• 当传入带href的props时，优先匹配第一个重载（明确要求hrefLang），缺失该属性则直接报错
• 不传入href时，匹配第二个重载，无需hrefLang
  这种顺序匹配的机制避免了联合类型的结构兼容性歧义，因此能正确触发校验。

正确的泛型条件类型写法 #

要让条件类型生效，需将泛型参数与href的存在性直接绑定：

type HybridProps<Href extends string | undefined = undefined> = 
  Href extends string 
    ? { href: Href; hrefLang: string; children: React.ReactNode }
    : { href?: never; children: React.ReactNode };

const Hybrid = <Href extends string | undefined = undefined>(
  props: HybridProps<Href>
) => {
  if (props.href) {
    return <a href={props.href} hrefLang={props.hrefLang}>{props.children}</a>;
  }
  return <button>{props.children}</button>;
};

此时TypeScript会根据传入的href自动推断泛型参数Href的类型，从而正确触发hrefLang的必填校验。

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