Vue3组合式API中Exclude工具类型引发Prop校验错误问题

问题原因 #

这个现象不属于框架Bug，本质是defineProps两种写法的编译逻辑差异导致的：

• 当你使用纯泛型写法defineProps<Type>()时，Vue编译器需要在编译阶段静态分析传入的TS类型，自动生成对应的运行时prop校验规则。但TS类型在编译为JS后会被完全擦除，Vue的静态类型分析能力有限，无法完整解析Exclude这类条件工具类型的运算结果，只能识别到外层的Person对象类型，因此生成的运行时校验仅接受Object类型，传入字符串'UNLOADED'时就会抛出警告。
• 你写的Options API版本之所以正常，是因为你手动显式指定了type: [Object, String]作为运行时校验规则，PropType<>仅用于TS层面的类型标注，完全不影响运行时逻辑，自然不会出现校验错误。

Composition API 规避方案 #

你可以根据项目习惯选任意一种方案解决：

1. 手动指定运行时校验规则（最稳妥）
   沿用Options API的思路，不使用纯泛型写法，在defineProps里显式声明运行时type，同时用PropType对齐TS类型：

   <script setup lang="ts">
   import { type PropType } from 'vue'
   
   const props = defineProps({
     status: {
       type: [Object, String] as PropType<Exclude<Status, null>>,
       required: true
     }
   })
   </script>
   

2. 显式拆解类型，避免在defineProps里直接使用高级工具类型
   提前把排除null后的类型显式定义为结构清晰的联合类型，让Vue编译器能直接静态识别所有类型分支，不需要解析Exclude的运算逻辑：

   <script setup lang="ts">
   // 提前显式定义类型，不要在defineProps里直接做Exclude运算
   type ValidStatus = Person | 'UNLOADED'
   const props = defineProps<{
     status: ValidStatus
   }>()
   </script>
   

注：由于TS本身没有提供完整的运行时类型反射能力，Vue对TS类型的静态分析仅能覆盖简单类型、直接联合、接口等常见场景，涉及条件类型、映射类型等高级TS类型的场景，手动指定运行时校验规则是兼容性最好的方案。

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