Skip to content

Vue + TypeScript 类型安全:defineModel、泛型组件与类型测试 ​

1. 学完这一节你能做什么 ​

三条可以直接验收的目标:

  • 能指出一个 Vue 项目里五处最容易漏掉类型的接口,并说出各自的后果。
  • 会判断一个组件的类型问题该在 defineModel、generic 还是运行时校验层解决。
  • 能把"组件对外契约"写成 expectTypeOf 断言,并让它在 CI 里真实变红。

外加一条边界:能说清类型测试覆盖不到什么,不至于把类型通过当成功能通过。

2. 这张图在技术体系里的位置 ​

组件类型安全横跨三个层面:语言层(TS 本体)、编译层(vue-tsc 与编译器宏)、验证层(类型测试)。本篇只讲后两层与 Vue 的交界处,TS 语法本身不展开。

图上有一处必须记住的分岔:C 往上是编译期,G 往下是运行期。两条路不能互相替代,这一点在 6.1 会再讲一遍。

3. 导入:一次没有报错的线上事故 ​

2026 年 3 月,某结算页把金额传成了字符串。组件里 props.amount 声明为 number,父组件写的是 :amount="row.total",而 row.total 来自接口,实际返回 "1288.00"。构建通过,单测通过,vue-tsc 也没报错——因为父组件的 row 是从 ref<any> 里取的。

结果:amount * 100 得到 128800(字符串转数字正常),但 amount.toFixed(2) 之外的金额校验用 amount > limit 比较,字符串与数字比较时走了隐式转换,"1000.00" > 999 判为 false,超额订单漏过校验。

这个问题有三个可能的修法,分别落在不同层。要判断选哪个,得先知道类型是在哪里漏掉的。

4. 概念拆解 ​

4.1 五处类型逃逸点 ​

逃逸点典型写法后果
props 声明defineProps({ item: Object })父组件字段名写错不报错
事件声明defineEmits(['change'])参数类型全丢,事件名拼错无提示
slot props<slot :row="row" /> 不声明模板里 row 退回 any
模板 refconst el = ref()el.value.xxx 无补全无校验
provide/injectprovide('store', store)注入方拿到 unknown

反例说明第三行:很多项目写了 defineSlots,但只写了键名不写参数类型,<slot name="cell" /> 的 cell 就成了 (...args: any[]) => any。看起来声明了,实际什么都没约束。

模板 ref 是最容易被放过的一处。Vue 3.5 起 useTemplateRef('input') 会读取模板上 ref="input" 的元素类型自动推导,不需要再手写 ref<HTMLInputElement | null>(null)。这是投入产出比最高的一次清理。

判断顺序

先修 props 与 emits(影响所有调用方),再修 slot props(影响模板),最后修 ref 与 inject(影响单文件内部)。反过来的收益小得多。

4.2 defineModel 的类型从哪来 ​

defineModel() 是编译器宏,展开成一个 modelValue prop 加一个 update:modelValue 事件。类型参数写在宏上,父组件的 v-model 就受这个类型约束。

vue
<!-- app/components/PriceInput.vue —— Vue 3.5.x -->
<script setup lang="ts">
const amount = defineModel<number>('amount', { required: true })

const [currency, currencyModifiers] = defineModel<string>('currency', {
  default: 'CNY',
  set: (v) => (currencyModifiers.uppercase ? v.toUpperCase() : v),
})

const emit = defineEmits<{ submit: [total: number] }>()
</script>

<template>
  <input :value="amount" type="number"
    @input="amount = Number(($event.target as HTMLInputElement).value)">
  <button @click="emit('submit', amount)">提交</button>
</template>

三个易错点。第一,required: true 不是装饰:父组件漏传 v-model:amount 时直接编译报错。第二,修饰符要通过解构第二个返回值拿到,手动声明 currencyModifiers prop 是 3.4 之前的写法。第三,不要再手写同名 modelValue prop,宏已声明它。

组件有多个绑定值时,写多个 defineModel('firstName')、defineModel('lastName'),不要图省事用一个对象 model 包住所有字段。对象 model 每次更新都换引用,父级一改就触发整棵子树重渲染,类型上也只是一个字段全可选的 Partial<T>,等于把校验又还给了运行时。字段多到需要分组时,正确做法是拆组件,而不是把 model 做大。

这里补一个推导链条,说明为什么"类型参数写在宏上"是必要的:defineModel<number>('amount') 展开后,编译器生成的 props 类型是 { amount: number },emits 类型是 { 'update:amount': [value: number] }。父组件写 v-model:amount="total" 时,total 的类型必须能赋给 number,同时 total 的写入位置接收到的值也是 number。两个方向的约束来自同一个类型参数,这就是它比手写 props: { amount: Number } 强的地方——后者在编译期就丢掉了信息,只留一个运行时构造函数。

4.3 泛型组件:让类型跟着数据走 ​

vue
<!-- app/components/DataTable.vue —— Vue 3.3+ -->
<script setup lang="ts" generic="T extends { id: string | number }">
const props = defineProps<{ rows: T[]; rowKey?: (row: T, i: number) => string | number }>()

const emit = defineEmits<{ select: [row: T]; remove: [id: T['id']] }>()

defineSlots<{
  cell(p: { row: T; index: number }): any
  empty(): any
}>()
</script>

<template>
  <ul>
    <li v-for="(row, i) in props.rows" :key="props.rowKey ? props.rowKey(row, i) : row.id">
      <slot name="cell" :row="row" :index="i" />
      <button @click="emit('remove', row.id)">删除</button>
    </li>
  </ul>
</template>

父组件写 <DataTable :rows="users" @remove="(id) => ..."> 时,id 被推导成 User['id'],#cell="{ row }" 里的 row 是 User。类型参数穿过 props、emits、slots 三处,模板不再是类型黑洞。

不顺这个思路走的写法会怎样:把 rows 声明成 any[],则 row.id 是 any,@remove 的参数是 any,#cell 里的 row 也是 any。三处全部放行,且没有任何一处会提示你"这里本可以推断"。这类代码在 code review 里几乎看不出来,因为它们不报错。

约束本身也在干活:T extends { id: string | number } 让 row.id 在模板里可直接当 key 用,去掉约束这行即报错。顺着同一思路可以把列定义也泛型化——columns: { key: keyof T; title: string }[]——列名写错、把不存在的字段塞进表格,都会在编译期而不是上线后暴露。

两个边界

generic 只能写在 <script setup> 上,Options API 不支持。另外再包一层 BaseTable 转发 props 时类型参数会丢,要么在新组件重新声明 generic,要么用 ComponentProps<typeof DataTable> 显式传递。泛型组件的模板 ref 也不能用 InstanceType,须用 ComponentExposed<typeof DataTable>。

4.4 类型测试测的是契约 ​

vue-tsc --noEmit 保证源码自身没有类型错误,保证不了对外契约没被改坏。有人把 amount 从 number 改成 number | string,源码照样编译通过,调用方可能已经出错。类型测试补的就是这一层。

ts
// tests/types/price-input.test-d.ts —— Vitest 5.1.x
import { describe, expectTypeOf, test } from 'vitest'
import type { ComponentEmits, ComponentProps } from 'vue-component-type-helpers'
import PriceInput from '~/components/PriceInput.vue'

type Props = ComponentProps<typeof PriceInput>
type Emits = ComponentEmits<typeof PriceInput>

describe('PriceInput 对外契约', () => {
  test('amount 必填且只能是 number', () => {
    expectTypeOf<Props['amount']>().toEqualTypeOf<number>()
  })
  test('currency 带默认值,父级视角仍是可选', () => {
    // 预期通过:default 不改变父组件传参视角,仍是 string | undefined
    expectTypeOf<Props['currency']>().toEqualTypeOf<string | undefined>()
  })
  test('错误用法必须被拒绝', () => {
    // @ts-expect-error amount 不接受字符串
    const bad: Props = { amount: '100' }
    void bad
  })
})

运行结果(预期输出):

bash
$ pnpm exec vitest --typecheck --run
 ✓ tests/types/price-input.test-d.ts (3 tests) 1241ms
   Test Files  1 passed (1)
        Tests  3 passed (3)
     Type Errors  no errors

这套门禁在 CI 里的顺序不能随意。vue-tsc --noEmit 快、覆盖面大,先跑;类型契约断言慢一点但能定位到具体 API,其次;行为测试与构建最后。反过来先跑 E2E 再查类型,等于把最贵的检查放在最前面。

还有一个实际耗时的坑:把 tests/、*.stories.ts 一并塞进应用侧 tsconfig,vue-tsc 会把与本次改动无关的代码全量检查一遍,冷启动从 40 秒涨到 3 分以上。用 project references 拆成 app / node / test 三份配置(Nuxt 4 生成的 .nuxt/tsconfig.app.json 与 tsconfig.node.json 就是同一思路),只让需要的那份进流水线,检查范围与缓存命中率都会改善。

5. 动手任务 ​

目标:在一个最小项目里跑通"类型契约变红"的完整链路。

bash
# 预期输出:安装完成后 node_modules 中存在 vue-tsc 可执行文件
pnpm add -D vue-tsc@3.3.14 vitest@5.1.0 vue-component-type-helpers@3.3.14
pnpm exec vue-tsc --version   # 预期输出 Version 3.3.14

配置要点只有三行:

ts
// vitest.config.ts —— Vitest 5.1.x
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  test: {
    typecheck: {
      enabled: true,
      checker: 'vue-tsc',                        // tsc 不认识 SFC
      include: ['tests/types/**/*.test-d.ts'],
      tsconfig: './tsconfig.app.json',           // 必须带 vueCompilerOptions
    },
  },
})

验证任务:把 PriceInput.vue 里的 defineModel<number> 改成 defineModel<number | string>,重跑上一条命令,预期看到 Type Errors found 1 error 且指向 amount 那一行。看到红再改回来,这个循环做完才算掌握。

6. 三条反直觉的判断 ​

6.1 很多人以为类型检查过了就等于数据合法,实际上是两回事。 defineProps 的泛型写法是纯编译期的,运行时没有任何校验。父组件传 undefined、接口少返回一个字段,类型系统一律不管,模板只会安静地渲染成空。需要运行时兜底的地方(接口响应、URL 参数、localStorage)要在数据入口用 zod 或 valibot 解析一次,把 unknown 收窄成具体类型再往下传。

6.2 很多人以为 checker 写不写都行,实际上写错就是全绿的假象。 tsc 不认识 .vue,用默认 checker 会整片跳过模板里的错误,而 typecheck.include 只收 *.test-d.ts,最后得到一个"全绿但什么都没检查"的结果。同理 typecheck.tsconfig 指到 node 侧配置也会漏掉模板推断。

6.3 很多人以为给 defineModel 加 default 更安全,实际上它会在父子之间制造不同步。 官方文档明确警告过:父组件的 ref 仍是 undefined,子组件却拿到默认值,用户一操作就分叉。default 与 required 二选一时优先 required。

三类问题的修法不同,判断依据也不同。6.1 属于分层问题,类型层做不成运行时校验,只能靠解析器补;6.2 属于配置问题,改一行 checker 就解决;6.3 属于语义问题,得先决定"这个值到底归谁管"——归父组件管就 required,归子组件管就该在子组件内部持有状态,而不是假装成一个双向绑定。

一个只有实际写过类型测试的人才知道的细节

defineModel<string>('currency', { default: 'CNY' }) 在类型测试里断言 Props['currency'] 时,得到的不是 string 而是 string | undefined。因为 ComponentProps 描述的是父组件传参视角,而带默认值的 prop 从父级看依然可以省略。第一次写这条断言的人几乎都会先写成 toEqualTypeOf<string>(),然后盯着那条报错看很久。

7. 迁移练习 ​

7.1 你所在项目有一个 <Select> 组件,options 用 any[],v-model 用 defineModel() 无类型参数。请写出改造后的泛型签名,并说明为什么 id 的类型不能直接用 string。

7.2 现有 CI 只跑 vitest run。请给出加入类型门禁后的执行顺序,并说明为什么不能把 --typecheck 放在最前面。

7.3 有人提议"既然有类型测试,就把内部实现类型也锁死"。请给出反对的两条理由,并说明类型测试应该只测哪四类接口。

8. 名词与版本对照 ​

术语英文一句话解释
类型逃逸type escape本该被约束的值退化成 any 或 unknown 的位置
编译器宏compiler macro编译期展开的语法,如 defineModel、defineSlots,运行时不存在
泛型组件generic component通过 generic 属性让类型参数穿透到模板的组件
契约测试contract test只断言对外接口形状、不断言内部实现的测试
类型收窄type narrowing通过判断把宽类型缩小到具体类型的过程
项目引用project references把 tsconfig 拆成 app / node / test 三份以缩小检查范围
字面量保留literal inferencesatisfies 校验结构同时不改写推导出的字面量类型

截至 2026 年 11 月,本文版本基线为 Vue 3.5.45(vue@latest,3.6 仍在 RC,最新 3.6.0-rc.15)、vue-tsc 3.3.14、vue-component-type-helpers 3.3.14、Vitest 5.1.0。defineModel 自 3.4 起稳定,generic 自 3.3 起可用,useTemplateRef 自 3.5 起可用,三处宏的签名以官方 组合式 API 的 TypeScript 一节 与 language-tools 仓库 为准。

最后给一条明确的判断:不建议把 any 当作"暂时先这样"的过渡手段。如果一个 any 的存在理由是"这里不会出错",它就应该被删掉。真正需要保留的只有两类——与无类型的第三方脚本交互,以及渐进迁移中明确标记"类型待补"的模块边界;后者必须在同一个迭代里清掉,否则它会成为下一个事故的入口。