TypeScript 集成

下面，我们来系统的梳理关于 Vue + TypeScript 深度集成 的基本知识点：

一、TypeScript 与 Vue 集成概述

1.1 为什么需要 TypeScript

类型安全：编译时类型检查，减少运行时错误
代码智能：强大的IDE智能提示和自动补全
可维护性：清晰的接口定义和类型约束
团队协作：统一的代码规范和接口约定
重构信心：安全地进行大规模代码重构

1.2 Vue 与 TypeScript 集成方式

集成方式	适用场景	特点
选项式API	传统Vue项目迁移	兼容性好，学习曲线平缓
组合式API	新项目，复杂逻辑	更好的类型推断，更灵活
Class API	面向对象背景开发者	Vue 2主流方式，Vue 3可选
`<script setup>`	现代Vue开发	最简洁的语法，最佳类型支持

二、基础环境配置

2.1 创建支持 TypeScript 的 Vue 项目

使用 Vite 创建：

npm create vite@latest my-vue-ts-app -- --template vue-ts

使用 Vue CLI 创建：

vue create my-vue-ts-app
# 选择 Manually select features → 勾选 TypeScript

2.2 关键配置文件

tsconfig.json

{"compilerOptions": {"target": "ESNext","module": "ESNext","strict": true,"jsx": "preserve","moduleResolution": "node","esModuleInterop": true,"skipLibCheck": true,"forceConsistentCasingInFileNames": true,"baseUrl": ".","paths": {"@/*": ["src/*"]},"types": ["vite/client"],"lib": ["ESNext", "DOM", "DOM.Iterable"]},"include": ["src/**/*.ts","src/**/*.d.ts","src/**/*.tsx","src/**/*.vue"],"exclude": ["node_modules"]
}

vite.config.ts (Vite 项目)

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'url'export default defineConfig({plugins: [vue()],resolve: {alias: {'@': fileURLToPath(new URL('./src', import.meta.url))}},server: {port: 8080}
})

三、组件开发模式

3.1 组合式API + `<script setup>`

<script setup lang="ts">
import { ref, computed } from 'vue'// Props 类型定义
interface Props {title: stringcount?: number
}const props = defineProps<Props>()// 事件声明
const emit = defineEmits<{(e: 'update:count', value: number): void
}>()// 响应式数据
const message = ref<string>('Hello TS!')// 计算属性
const reversedMessage = computed(() => {return message.value.split('').reverse().join('')
})// 方法
const increment = () => {emit('update:count', (props.count || 0) + 1)
}
</script><template><div><h1>{{ title }}</h1><p>{{ message }} → {{ reversedMessage }}</p><button @click="increment">Count: {{ count || 0 }}</button></div>
</template>

3.2 选项式API类型支持

<script lang="ts">
import { defineComponent } from 'vue'export default defineComponent({props: {title: {type: String,required: true},count: {type: Number,default: 0}},emits: ['update:count'],data() {return {message: 'Hello TS!' as string}},computed: {reversedMessage(): string {return this.message.split('').reverse().join('')}},methods: {increment(): void {this.$emit('update:count', this.count + 1)}}
})
</script>

四、类型系统增强

4.1 全局类型声明

声明全局属性

// src/types/index.d.ts
import { Router } from 'vue-router'declare module '@vue/runtime-core' {interface ComponentCustomProperties {$router: Router$translate: (key: string) => string}
}

扩展全局组件类型

declare module '@vue/runtime-core' {export interface GlobalComponents {RouterLink: typeof import('vue-router')['RouterLink']RouterView: typeof import('vue-router')['RouterView']BaseButton: typeof import('./components/BaseButton.vue')['default']}
}

4.2 复杂类型工具

使用泛型约束 Props

import { PropType } from 'vue'interface User {id: numbername: stringemail: string
}export default defineComponent({props: {user: {type: Object as PropType<User>,required: true},permissions: {type: Array as PropType<('read' | 'write' | 'delete')[]>,default: () => ['read']}}
})

条件类型

type ButtonVariant = 'primary' | 'secondary' | 'text'
type ButtonSize = 'small' | 'medium' | 'large'interface ButtonProps {variant?: ButtonVariantsize?: ButtonSizedisabled?: boolean
}// 基于 Props 推导事件类型
type ButtonEmits = {click: [event: MouseEvent]hover: [isHovering: boolean]
}

五、状态管理与类型安全

5.1 Pinia 状态管理

类型化 Store

// stores/user.ts
import { defineStore } from 'pinia'interface User {id: numbername: stringemail: string
}interface UserState {currentUser: User | nullisAuthenticated: boolean
}export const useUserStore = defineStore('user', {state: (): UserState => ({currentUser: null,isAuthenticated: false}),actions: {async login(credentials: { email: string; password: string }) {const response = await api.login(credentials)this.currentUser = response.userthis.isAuthenticated = true},logout() {this.currentUser = nullthis.isAuthenticated = false}},getters: {username: (state) => state.currentUser?.name || 'Guest'}
})

5.2 Vuex 类型增强 (Vue 2)

import { createStore } from 'vuex'interface State {count: numberuser: User | null
}const store = createStore<State>({state: {count: 0,user: null},mutations: {setUser(state, payload: User) {state.user = payload},increment(state) {state.count++}},actions: {async fetchUser({ commit }, id: number) {const user = await api.getUser(id)commit('setUser', user)}},getters: {doubleCount: state => state.count * 2}
})

六、路由系统类型化

6.1 Vue Router 类型集成

import { createRouter, createWebHistory } from 'vue-router'// 定义路由元信息类型
declare module 'vue-router' {interface RouteMeta {requiresAuth?: booleantitle: string}
}const router = createRouter({history: createWebHistory(),routes: [{path: '/',component: () => import('@/views/Home.vue'),meta: { title: 'Home' }},{path: '/profile',component: () => import('@/views/Profile.vue'),meta: { requiresAuth: true,title: 'User Profile' }},{path: '/:pathMatch(.*)*',component: () => import('@/views/NotFound.vue'),meta: { title: 'Page Not Found' }}]
})// 导航守卫中使用类型
router.beforeEach((to, from) => {if (to.meta.requiresAuth && !isAuthenticated()) {return '/login'}
})

七、高级类型技巧

7.1 泛型组件

<script setup lang="ts" generic="T">
import { ref } from 'vue'defineProps<{items: T[]selected: T
}>()defineEmits<{(e: 'select', item: T): void
}>()
</script><template><ul><li v-for="item in items" :key="item.id"@click="$emit('select', item)">{{ item }}</li></ul>
</template>

7.2 类型安全的模板引用

<script setup lang="ts">
import { ref } from 'vue'const inputRef = ref<HTMLInputElement | null>(null)const focusInput = () => {inputRef.value?.focus()
}
</script><template><input ref="inputRef" type="text"><button @click="focusInput">Focus Input</button>
</template>

7.3 条件渲染类型收窄

interface User {id: numbername: string
}const user = ref<User | null>(null)// 使用类型守卫
function isUser(user: User | null): user is User {return user !== null
}// 在模板中使用
<template><div v-if="isUser(user)"><!-- 此处 user 类型为 User --><h1>{{ user.name }}</h1></div><div v-else>Loading...</div>
</template>

八、测试策略

8.1 组件单元测试

import { mount } from '@vue/test-utils'
import Counter from '@/components/Counter.vue'describe('Counter.vue', () => {it('emits increment event when clicked', async () => {const wrapper = mount(Counter, {props: {initialCount: 5}})await wrapper.find('button').trigger('click')expect(wrapper.emitted()).toHaveProperty('increment')expect(wrapper.find('button').text()).toContain('6')})
})

8.2 类型测试

// 使用 tsd 进行类型测试
import { expectType } from 'tsd'
import { useUserStore } from '@/stores/user'const store = useUserStore()// 测试 state 类型
expectType<number>(store.count)
expectType<User | null>(store.user)// 测试 getter 类型
expectType<string>(store.username)// 测试 action 类型
expectType<(credentials: { email: string; password: string }) => Promise<void>>(store.login)

九、性能优化

9.1 类型导入优化

// 使用类型导入减少运行时开销
import type { Router } from 'vue-router'function useNavigation(router: Router) {// ...
}

9.2 避免 any 类型

// 使用 unknown 替代 any
function safeParse(data: string): unknown {return JSON.parse(data)
}// 使用类型守卫
function isUser(data: unknown): data is User {return typeof data === 'object' && data !== null && 'id' in data && 'name' in data
}// 使用类型断言
const userData = safeParse(localStorage.getItem('user') || '{}') as User

十、实践

10.1 项目结构组织

src/
├── assets/
├── components/
│   ├── ui/
│   └── business/
├── composables/         # 组合式函数
├── layouts/
├── router/
├── stores/
├── types/               # 全局类型声明
│   ├── api.d.ts
│   ├── components.d.ts
│   └── index.d.ts
├── utils/               # 工具函数
├── views/
├── App.vue
└── main.ts

10.2 自定义 ESLint 规则

// .eslintrc.js
module.exports = {rules: {'@typescript-eslint/no-explicit-any': 'error','@typescript-eslint/explicit-function-return-type': ['error',{allowExpressions: true}],'vue/require-typed-props': 'error','vue/require-typed-emits': 'error'}
}

十一、常见问题解决

11.1 第三方库类型缺失

# 安装社区维护的类型声明
npm install -D @types/lodash# 对于无类型声明的库
// src/shims.d.ts
declare module 'untyped-module' {const content: anyexport default content
}

11.2 模板事件处理类型

<script setup lang="ts">
const handleChange = (e: Event) => {// 类型收窄if (e.target instanceof HTMLInputElement) {console.log(e.target.value)}
}
</script><template><input type="text" @input="handleChange">
</template>

11.3 全局组件类型扩展

// src/types/components.d.ts
import type { DefineComponent } from 'vue'declare module 'vue' {export interface GlobalComponents {BaseButton: DefineComponent<{variant?: 'primary' | 'secondary'size?: 'small' | 'medium' | 'large'}>Icon: DefineComponent<{name: stringsize?: number}>}
}