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 |
| 模板 ref | const el = ref() | el.value.xxx 无补全无校验 |
| provide/inject | provide('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 就受这个类型约束。
<!-- 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 泛型组件:让类型跟着数据走
<!-- 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,源码照样编译通过,调用方可能已经出错。类型测试补的就是这一层。
// 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
})
})运行结果(预期输出):
$ 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. 动手任务
目标:在一个最小项目里跑通"类型契约变红"的完整链路。
# 预期输出:安装完成后 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配置要点只有三行:
// 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 inference | satisfies 校验结构同时不改写推导出的字面量类型 |
截至 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 的存在理由是"这里不会出错",它就应该被删掉。真正需要保留的只有两类——与无类型的第三方脚本交互,以及渐进迁移中明确标记"类型待补"的模块边界;后者必须在同一个迭代里清掉,否则它会成为下一个事故的入口。