18.5 Vue + TS 常见类型问题与解决方案

即便 Vue 3 对 TypeScript 的支持已经相当深入，实际开发中仍会遇到不少让类型检查“报红”的场景。这些问题往往不是 Vue 或 TS 本身的 bug，而是对类型推导规则不熟悉导致的。下面列举了开发中最常见的几个类型问题，并给出对应的解决思路。

1. Props 类型定义后，模板中使用时报“可能为 undefined”

<script setup lang="ts">
defineProps<{ title?: string }>()
</script>
<template>
  <h1>{{ title.length }}</h1>  <!-- 报错：title 可能为 undefined -->
</template>

原因：可选 prop 没有默认值，类型里自然包含 undefined，TS 会强制你做空值检查。

解决方案：

用 withDefaults 提供默认值，类型会自动收窄。

  <script setup lang="ts">
  const props = withDefaults(defineProps<{ title?: string }>(), {
    title: '默认标题'
  })
  </script>

或在模板中使用可选链：{{ title?.length ?? 0 }}。

2. defineEmits 定义的事件，触发时类型不匹配

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'update', id: number): void
}>()

// 调用时：
emit('update', '123')  // 报错：不能将类型“string”分配给类型“number”
</script>

原因：类型签名里声明了 id: number，传入字符串自然报错。但更常见的是忘记定义参数类型。

解决方案：

严格按照声明传入正确类型。
如果事件参数复杂，可以单独定义一个 interface：

  interface UpdatePayload { id: number, name: string }
  const emit = defineEmits<{ (e: 'update', payload: UpdatePayload): void }>()

3. 模板 ref 获取组件实例，类型推导为 any

<script setup lang="ts">
import MyModal from './MyModal.vue'
const modal = ref(null)  // 此时 modal.value 类型为 null
</script>
<template>
  <MyModal ref="modal" />
</template>

原因：ref(null) 不包含任何类型信息，Vue 无法推断出你要引用什么组件。

解决方案：

显式指定 ref 类型：

  import type { ComponentPublicInstance } from 'vue'
  const modal = ref<InstanceType<typeof MyModal> | null>(null)

或者直接使用组件类型（如果组件通过 defineExpose 暴露了方法）：

  import MyModal from './MyModal.vue'
  const modal = ref<InstanceType<typeof MyModal>>()

调用方法时就能获得类型提示：

  modal.value?.open()

4. provide / inject 丢失类型信息

<!-- 祖先组件 -->
<script setup lang="ts">
provide('user', { name: 'Alice', age: 30 })
</script>

<!-- 后代组件 -->
<script setup lang="ts">
const user = inject('user')  // 类型为 unknown
</script>

原因：provide 和 inject 的 key 是字符串，TS 无法自动桥接类型。

解决方案：

使用 InjectionKey 创建类型安全的 key：

  // types.ts
  import type { InjectionKey } from 'vue'
  export interface User { name: string, age: number }
  export const userKey: InjectionKey<User> = Symbol('user')

  <!-- 祖先 -->
  <script setup lang="ts">
  import { provide } from 'vue'
  import { userKey } from './types'
  provide(userKey, { name: 'Alice', age: 30 })
  </script>

  <!-- 后代 -->
  <script setup lang="ts">
  import { inject } from 'vue'
  import { userKey } from './types'
  const user = inject(userKey)  // 类型自动推导为 User | undefined
  </script>

5. 动态组件 <component :is> 类型不明确

<script setup lang="ts">
import CompA from './CompA.vue'
import CompB from './CompB.vue'
const current = ref('CompA')
</script>
<template>
  <component :is="current" />  <!-- current 是字符串，类型不匹配 -->
</template>

原因：is 可以接受组件对象或字符串，当接收字符串时 TS 无法关联到具体组件，导致 props/events 类型丢失。

解决方案：

如果已知组件映射，可以用对象或 DefineComponent 类型：

  import CompA from './CompA.vue'
  import CompB from './CompB.vue'
  import type { DefineComponent } from 'vue'

  const compMap: Record<string, DefineComponent> = { CompA, CompB }
  const currentComp = computed(() => compMap[current.value])

然后模板中使用 :is="currentComp"。

更常见的做法是使用组件对象本身：

  const currentTab = ref<DefineComponent>(CompA)

6. 全局属性扩展后，模板中访问报“类型上不存在属性”

你通过 app.config.globalProperties 挂载了 $http，但在任何组件的 <script setup> 中访问 $http 时 TS 报错。

解决方案：需要做全局类型声明扩展。

在项目 src 目录下创建 vue-global.d.ts（或其他 .d.ts 文件）：

import type { AxiosInstance } from 'axios'

declare module 'vue' {
  interface ComponentCustomProperties {
    $http: AxiosInstance
  }
}

确保该文件被 tsconfig.json 的 include 覆盖，之后任何组件中 this.$http 或模板表达式中的 $http 都拥有完整类型。

7. 使用 defineProps 解构导致响应式丢失与类型窄化问题

<script setup lang="ts">
const { title } = defineProps<{ title: string }>()
// title 现在只是一个普通 string，不是响应式引用
</script>

原因：直接解构 props 会丢失 Vue 的响应式追踪，且 TypeScript 在结构分支下可能将类型收窄为字面量。

解决方案：

避免直接解构，通过 props.title 访问。
如果必须解构并且要保持响应式，可以使用 toRefs：

  import { toRefs } from 'vue'
  const props = defineProps<{ title: string }>()
  const { title } = toRefs(props) // title 是 Ref<string>

Vue 3.3+ 提供了 defineProps 的解构语法糖（需开启 destructureProps 编译选项），但要注意类型变化，建议阅读官方 RFC。

8. 第三方库缺少 TS 类型声明

比如引入一个没有 @types/xxx 的库，直接 import 会报“找不到模块”的错误。

解决：

如果库比较常见，先查询 DefinitelyTyped 是否有社区提供：npm i -D @types/xxx。
如果完全没有，可以自己创建一个简单的声明文件 shims.d.ts：

  declare module 'some-lib' {
    export function doSomething(p: string): void
  }

最快速的临时方案是在 env.d.ts 中添加：

  declare module 'some-lib'

这样所有导出就是 any，至少不会编译报错。

这些场景几乎覆盖了日常 Vue + TS 开发中 90% 的类型报错。核心原则是：明确告诉 TypeScript 你想要什么类型，而不是等着它猜。善用 interface、泛型和类型声明文件，可以有效提升开发体验，让类型检查成为你的助手，而不是绊脚石。