Vue 3.5新增的withDefaults到底有什么用？

最近不少前端开发者在讨论Vue 3.5的更新，其中有个叫withDefaults的API被反复提及，有人说它“解决了TypeScript项目的痛点”，也有人疑惑“不就是设置默认值吗？和以前有什么区别？”，作为每天和Vue打交道的开发者，我也特意研究了这个新工具，发现它确实在某些场景下能大幅提升开发效率，今天就用问答的形式，和大家聊清楚这个“看似简单却不简单”的新功能。

为什么Vue要新增withDefaults？传统写法有什么问题？

要理解withDefaults的价值，得先回到Vue 3的TypeScript开发场景，过去用Vue 3写组件时，如果你想同时声明props的类型和默认值，可能会遇到两个麻烦：

麻烦1：类型声明和默认值重复劳动
在Vue 3中，defineProps有两种模式：运行时模式（传对象）和类型驱动模式（传类型），用类型驱动模式时，写法是这样的：

const props = defineProps<{
  size: 'small' | 'medium' | 'large'
  disabled: boolean
  label: string
}>()

这时候如果要给size设置默认值'medium'，或者给label设置默认值'点击按钮'，就必须额外用withDefaults（以前没有的话，可能需要手动在组件里处理默认值逻辑），而如果用运行时模式，虽然可以直接在对象里写default，但类型需要靠PropType手动标注，

const props = defineProps({
  size: {
    type: String as PropType<'small' | 'medium' | 'large'>,
    default: 'medium'
  },
  // ...其他props
})

这种写法虽然能同时处理类型和默认值,但类型标注的代码量明显更多，尤其是当props类型复杂时（比如联合类型、对象类型），容易写错或者漏标。

麻烦2：类型推断容易出问题
假设你在类型驱动模式下直接给props变量设置默认值，TypeScript可能无法正确推断类型，比如你可能想这样写：

const props = defineProps<{
  size?: 'small' | 'medium' | 'large'
}>()
// 手动设置默认值
const defaultSize = props.size ?? 'medium'

但这种写法不仅增加了额外代码,还可能因为忘记处理undefined情况导致类型错误，更关键的是，组件的使用者在IDE中查看props类型时，不会看到默认值的提示——他们可能以为size是可选的，但不知道默认是'medium'，这会降低组件文档的可读性。

withDefaults的出现，就是为了在类型驱动模式下，让默认值的声明更简洁、类型更安全，同时保持代码的可维护性，简单说，它帮我们把“类型声明”和“默认值设置”这两件事合并到了一起，避免重复劳动，还能让TypeScript自动推断出更准确的类型。

withDefaults具体怎么用？举个实际例子

withDefaults的用法其实很简单，它本质上是一个包装函数，接收两个参数：一个是通过defineProps声明的类型（类型驱动模式），另一个是默认值对象，最终返回的是一个包含类型信息和默认值的props对象。

举个最常见的按钮组件例子：
我们需要定义一个Button组件，包含size（可选，默认'medium'）、type（可选，默认'button'）、disabled（可选，默认false）三个props，用withDefaults的写法是：

const props = withDefaults(defineProps<{
  size?: 'small' | 'medium' | 'large'
  type?: 'button' | 'submit' | 'reset'
  disabled?: boolean
}>, {
  size: 'medium',
  type: 'button',
  disabled: false
})

对比传统的运行时模式写法：

const props = defineProps({
  size: {
    type: String as PropType<'small' | 'medium' | 'large'>,
    default: 'medium'
  },
  type: {
    type: String as PropType<'button' | 'submit' | 'reset'>,
    default: 'button'
  },
  disabled: {
    type: Boolean,
    default: false
  }
})

明显能看出,withDefaults的写法更简洁：

• 类型声明集中在<>里，一目了然；

• 默认值单独放在一个对象里,修改时不用在类型和默认值之间来回切换；

• TypeScript会自动推断出props.size的类型是'small' | 'medium' | 'large'（而不是可选的string | undefined），因为默认值已经提供了，所以组件内部使用props.size时不需要处理undefined情况。

和传统写法比，withDefaults有哪些优势？

除了代码更简洁,withDefaults的核心优势体现在类型安全和开发体验上：

类型自动补全更准确

用类型驱动模式+withDefaults时，IDE（如VS Code）会根据默认值自动推断出props的最终类型，比如上面的size，虽然声明时是可选的（带），但因为设置了默认值'medium'，所以组件内部使用props.size时，类型会被推断为'small' | 'medium' | 'large'（非可选），这意味着你在代码里写props.size时，IDE会自动提示可能的取值，而不会出现undefined的情况。

避免默认值与类型不匹配的错误

假设你不小心给size的默认值设置了'big'（不在声明的联合类型里），TypeScript会立刻报错：

withDefaults(defineProps<{ size?: 'small' | 'medium' | 'large' }>, {
  size: 'big' // 报错：类型'"big"'不能赋给类型'"small" | "medium" | "large"'
})

而传统的运行时模式中,这种错误只能在运行时被发现（比如组件渲染时可能不生效），或者需要手动检查类型是否匹配。withDefaults通过TypeScript的静态类型检查，提前拦截了这种低级错误。

组件文档更清晰

当其他开发者使用你的组件时,无论是通过IDE的悬停提示，还是通过文档工具（如Vue Docgen），都能直接看到props的默认值，比如悬停在Button组件的size属性上，提示会是：size?: 'small' | 'medium' | 'large'（默认值：'medium'），这比手动在注释里写默认值更可靠，减少了沟通成本。

使用withDefaults需要注意什么？

虽然withDefaults很方便，但实际使用时也有几个细节需要注意：

默认值的类型必须严格匹配声明的类型

前面提到的类型检查是双向的——不仅默认值不能超出声明的类型范围，声明的类型也不能遗漏默认值的可能取值，比如如果你声明size的类型是'small' | 'large'，却设置默认值为'medium'，TypeScript会立刻报错，这要求我们在设计props类型时，必须把默认值考虑进去，避免类型声明和实际使用脱节。

对象类型的默认值要用工厂函数

如果默认值是对象（比如style属性的默认值是{ color: 'red' }），需要像Vue 2的props一样，用工厂函数返回对象，避免多个组件实例共享同一个对象引用。

const props = withDefaults(defineProps<{
  style?: Record<string, string>
}>, {
  style: () => ({ color: 'red', fontSize: '14px' })
})

如果直接写style: { color: 'red' }，TypeScript不会报错，但运行时可能出现多个组件实例共享同一个对象的问题（比如一个组件修改了style.color，其他组件也会受影响），这一点和Vue 2的props默认值规则保持一致，需要特别注意。

只适用于类型驱动模式的defineProps

withDefaults是专门为defineProps的类型驱动模式设计的，如果你用的是运行时模式（传对象参数），则不需要也不能用withDefaults，因为运行时模式已经支持在default属性里设置默认值，而withDefaults的作用是补充类型驱动模式的默认值声明能力。

哪些场景最适合用withDefaults？

开发通用组件库

通用组件库（如按钮、表单、弹窗）通常需要为props提供合理的默认值，以降低使用者的学习成本，用withDefaults可以让组件代码更简洁，同时保证类型安全，比如一个Input组件的placeholder默认值设为'请输入内容'，maxLength默认设为50，这些都能通过withDefaults清晰声明。

团队协作的大型项目

大型项目中,组件可能被多个开发者修改。withDefaults将类型和默认值集中管理，减少了代码分散导致的错误，比如当需要调整某个props的默认值时，只需要修改withDefaults里的对象，而不用去类型声明里找对应的位置，降低了维护成本。

需要严格类型约束的项目

如果你在项目中启用了TypeScript的严格模式（strict: true），withDefaults能帮你避免很多类型错误，比如当组件的使用者没有传递size属性时，props.size会自动拥有默认值，TypeScript不会提示可能为undefined的错误，减少了不必要的可选链（）或空值合并（）操作。

withDefaults值得尝试吗？

从实际使用体验来看,withDefaults是Vue 3.5中非常实用的一个小改进，它没有改变Vue的核心逻辑，却精准解决了TypeScript项目中“props类型声明与默认值重复”的痛点，无论是开发新组件，还是重构旧代码，它都能让你的代码更简洁、更安全。

如果你还在为Vue 3的TypeScript开发效率发愁，不妨在下次写组件时试试withDefaults，只需要几行代码的调整，就能体验到类型安全和开发效率的双重提升——这大概就是Vue“渐进式改进”理念的最佳体现吧。