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}>}
}