TypeScript 在 Vue 项目中的深度实践指南

引言

随着前端工程化的发展，TypeScript 以其静态类型检查、代码提示和重构能力，逐渐成为 Vue 生态的核心技术栈之一。本文将结合 Vue 3 的 Composition API 和 Vuex 4，从项目初始化到高级特性，系统阐述 TypeScript 在 Vue 中的最佳实践。

一、项目初始化与配置

1. 创建支持 TypeScript 的 Vue 项目

使用 Vue CLI 或 Vite 创建项目时，直接勾选 TypeScript 选项：

js 复制代码

npm install -g @vue/cli
vue create my-vue-ts-project
# 选择 Manually select features → TypeScript

具体流程示意图：

↓切换选项回车选择 Manually select features
↓切换选项空格选中 Typescript
↓切换选项回车选择 3.x
是否使用Class风格装饰器，No
是否使用TypeScript和Babel的形式编译 JSX，No
ESLint的一些配置，默认就好

js 复制代码

>(*) Lint on save         // 保存的时候进行 Lint
 ( ) Lint and fix on commit   // 需要帮你进行fix（修理），不选

选择配置文件是单独存放，还是直接存放在package.json文件里（默认）

需不需要把配置保存下来，下次直接进行使用

完成创建

2. 核心配置文件 `tsconfig.json`

常用配置：

js 复制代码

{
  // 控制 TypeScript 编译器行为的选项
  "compilerOptions": {
    "target": "es5", // 设置编译后的 JavaScript 版本。例如，"es5"、"es6"、"es2017" 等
    "module": "esnext", // 设置模块系统。例如，"commonjs"、"amd"、"esnext" 等
    "outDir": "./dist", // 设置输出目录。例如，"dist"、"build" 等
    "strict": true, // 启用所有严格类型检查选项
    "esModuleInterop": true, // 允许导入非 ES 模块。
    "allowJs": true, // 允许导入/编译 JavaScript 文件。
    "sourceMap": true, // 设置源文件目录（生成相应的 .map 文件以便调试）。例如，"src"、"lib" 等
    "jsx": "preserve", // 设置 JSX 模式。例如，"preserve"、"react-jsx"、"react-jsxdev" 等
    "importHelpers": true, // 启用导入帮助程序
    "moduleResolution": "node", // 设置模块解析策略。例如，"node"、"classic" 等
    "skipLibCheck": true, // 跳过库文件检查。
    "allowSyntheticDefaultImports": true, // 允许合成默认导入。
    "forceConsistentCasingInFileNames": true, // 强制一致的文件名大小写。
    "useDefineForClassFields": true, // 使用定义类字段。
    "baseUrl": ".", // 设置基础 URL （模块解析的基地址）。
    "types": ["webpack-env"], // 设置类型。例如，"webpack-env"、"jest" 等
    "paths": {
      "@/*": ["src/*"]
    }, // 设置路径别名（路径映射）。例如，"@/*" 表示 "src/*"
    "lib": ["esnext", "dom", "dom.iterable", "scripthost"] // 设置库文件。例如，"esnext"、"dom"、"dom.iterable"、"scripthost" 等
  },
  // 指定希望编译器编译的文件或目录。同样可以使用 glob 模式
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "tests/**/*.ts",
    "tests/**/*.tsx"
  ],
  // "files": ["core.ts", "sys.ts", "types.ts", "scanner.ts", "parser.ts"], // 直接指定要编译的文件的列表，而不是使用 glob 模式。
  "exclude": ["node_modules"] // 指定不希望编译器编译的文件或目录。同样可以使用 glob 模式
  // 自动包含类型声明文件。例如，自动包含 node 的类型声明。
  // "typeAcquisition": {
  //   "include": ["jest"]
  // }
}

关键点：

strict: true 启用严格类型检查
paths 配置路径别名，避免相对路径地狱
Vite 项目需额外配置 types 字段

二、组件开发中的 TypeScript 实践

1. 基础组件开发

选项式 API + TypeScript

js 复制代码

<script lang="ts">
import { defineComponent } from 'vue';
 
export default defineComponent({
  name: 'HelloWorld',
  props: {
    msg: {
      type: String,
      required: true
    }
  },
  data() {
    return {
      count: 0
    };
  },
  methods: {
    increment(): void {
      this.count++;
    }
  }
});
</script>

组合式 API + `<script setup>`

js 复制代码

<script setup lang="ts">
import { ref } from 'vue';
 
const props = defineProps<{
  msg: string;
}>();
 
const count = ref(0);
const increment = () => {
  count.value++;
};
</script>

优势对比：

<script setup> 语法更简洁，自动类型推断
组合式 API 更适合复杂逻辑复用

2. 高级类型应用

接口定义复杂数据结构

js 复制代码

interface User {
  id: number;
  name: string;
  email: string;
  roles?: string[]; // 可选属性
}
 
// 在组件中使用
const user = ref<User>({
  id: 1,
  name: 'Alice',
  email: '[email protected]'
});

泛型实现可复用逻辑

ts 复制代码

// 泛型函数
function useFetch<T>(url: string): { data: Ref<T | null>; error: Ref<Error | null> } {
  const data = ref<T | null>(null);
  const error = ref<Error | null>(null);
 
  const fetchData = async () => {
    try {
      const response = await fetch(url);
      data.value = await response.json();
    } catch (err) {
      error.value = err as Error;
    }
  };
 
  return { data, error };
}
 
// 在组件中使用
const { data: userData } = useFetch<User>('/api/user/1');

装饰器模式（Vue Class Component）

ts 复制代码

import { Vue, Component, Prop } from 'vue-property-decorator';
 
@Component
export default class MyComponent extends Vue {
  @Prop({ type: String, required: true })
  readonly title!: string;
 
  message: string = 'Hello, TypeScript!';
 
  get reversedMessage(): string {
    return this.message.split('').reverse().join('');
  }
}

注意事项：

装饰器需在 tsconfig.json 中启用 experimentalDecorators
Vue 3 官方推荐使用组合式 API，装饰器模式逐渐被边缘化

三、Vuex 4 与 TypeScript 的深度集成

1. 定义 Store 类型

/store/types.ts

ts 复制代码

export interface State {
  count: number;
  user: User | null;
}
 
export interface Getters {
  doubleCount: (state: State) => number;
  userRole: (state: State) => string | null;
}
 
export interface Mutations {
  increment(state: State): void;
  setUser(state: State, user: User): void;
}
 
export interface Actions {
  fetchUser({ commit }: { commit: Commit }, userId: number): Promise<void>;
}

2. 创建类型安全的 Store

// store/index.ts

ts 复制代码

import { createStore } from 'vuex';
import { State, Getters, Mutations, Actions } from './types';
 
const store = createStore<State>({
  state: () => ({
    count: 0,
    user: null
  }),
  mutations: {
    increment(state) {
      state.count++;
    },
    setUser(state, user) {
      state.user = user;
    }
  },
  actions: {
    async fetchUser({ commit }, userId) {
      const user = await fetchUserFromAPI(userId);
      commit('setUser', user);
    }
  },
  getters: {
    doubleCount: (state) => state.count * 2,
    userRole: (state) => state.user?.role || null
  }
});
 
export default store;

3. 在组件中使用 Store

js 复制代码

<script setup lang="ts">
import { computed } from 'vue';
import { useStore } from 'vuex';
import { State } from '@/store/types';
 
const store = useStore<State>();
 
const count = computed(() => store.state.count);
const doubleCount = computed(() => store.getters.doubleCount);
 
const increment = () => {
  store.commit('increment');
};
 
const fetchUser = async () => {
  await store.dispatch('fetchUser', 1);
};
</script>

优势：

类型安全：避免拼写错误和类型不匹配
代码提示：IDE 自动提示 mutations、actions 和 getters
可维护性：清晰的类型定义便于团队协作

四、VUE3 模板中使用 TS 的方案

在 Vue 3 的模板中，不能直接使用 TypeScript 的完整语法（如 interface、type 等），但可以通过一些技巧实现类似类型断言的效果。以下是几种常见场景的解决方案：

1. 使用 `as` 进行类型断言（不推荐）

在模板中，你可以通过 as 强制指定类型，但这种方式通常用于处理第三方库或特殊场景，不推荐滥用，因为它会绕过 Vue 的响应式系统。

js 复制代码

<script setup lang="ts">
const rawData = { value: 42 } as { value: number }; // 在 script 中断言
</script>
 
<template>
  <!-- 模板中无法直接使用 as，但可以通过计算属性间接实现 -->
  <div>{{ (rawData as any).value }}</div>
</template>

注意：模板中的 as 语法是 TypeScript 的特性，但 Vue 模板编译器不会处理它。实际使用时，建议通过计算属性或方法处理类型问题。

2. 通过计算属性或方法处理类型

更推荐的方式是在 <script setup> 中处理类型逻辑，然后将结果暴露给模板：

js 复制代码

<script setup lang="ts">
interface ApiResponse {
  id: number;
  name: string;
}
 
const response = ref<any>({ id: 1, name: "Vue" }); // 假设初始为 any 类型
 
// 通过计算属性断言类型
const safeResponse = computed(() => response.value as ApiResponse);
</script>
 
<template>
  <div>{{ safeResponse.id }} - {{ safeResponse.name }}</div>
</template>

3. 模板中的类型安全实践

Vue 模板本身是类型安全的（通过 Volar 插件提供支持），但你需要确保：

Props 类型 ：通过 defineProps 声明类型。
事件类型 ：通过 defineEmits 声明类型。
响应式数据 ：使用 ref/reactive 时显式声明类型。

js 复制代码

<script setup lang="ts">
interface Item {
  id: number;
  text: string;
}
 
const props = defineProps<{
  items: Item[];
}>();
 
const emit = defineEmits<{
  (e: 'select', item: Item): void;
}>();
</script>
 
<template>
  <ul>
    <li 
      v-for="item in props.items" 
      :key="item.id"
      @click="emit('select', item)" <!-- 类型安全的 emit -->
    >
      {{ item.text }}
    </li>
  </ul>
</template>

4. 使用 `satisfies` 验证表达式类型（Vue 3.3+）

如果你需要验证模板中某个表达式的类型，可以使用 satisfies：

js 复制代码

<script setup lang="ts">
const config = {
  color: 'red'
} satisfies {
  color: string;
  size?: number;
};
</script>
 
<template>
  <div :style="{ color: config.color }"></div>
</template>

关键点：

模板中不能直接使用 TypeScript 语法 （如 as、interface），但可以通过 <script setup> 提前处理类型。
推荐做法 ：在 <script setup> 中完成所有类型逻辑，模板仅负责渲染。
工具支持 ：使用 VSCode + Volar 插件获得最佳类型提示体验。

五、常见问题与解决方案

1. 如何处理 Vue 单文件组件中的 `.vue` 类型声明？

在 src/shims-vue.d.ts 中添加：

js 复制代码

declare module '*.vue' {
  import { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

2. 如何解决第三方库的类型缺失问题？

安装官方类型声明：npm install --save-dev @types/lodash
自定义声明文件：在 src/types 目录下创建 .d.ts 文件

3. 如何优化 TypeScript 编译性能？

启用增量编译："incremental": true
跳过类型检查（开发环境）：vue-cli-service serve --skip-plugins typescript
使用 isolatedModules："isolatedModules": true

六、总结

TypeScript 在 Vue 项目中的应用，不仅提升了代码的可维护性和健壮性，还通过类型系统为团队协作提供了有力保障。从项目初始化到复杂状态管理，TypeScript 的深度集成需要开发者掌握类型定义、泛型、装饰器等高级特性。

推荐实践：

优先使用 <script setup> 语法
为复杂数据结构定义接口
深度集成 Vuex 类型
Vue3 模板中推荐使用计算属性或方法处理类型
合理使用泛型实现可复用逻辑

通过本文的实践指南，相信你能在 Vue 项目中充分发挥 TypeScript 的优势，构建出更高效、更可靠的前端应用。

TypeScript 在 Vue 项目中的深度实践指南

引言

一、项目初始化与配置

1. 创建支持 TypeScript 的 Vue 项目

2. 核心配置文件 tsconfig.json

二、组件开发中的 TypeScript 实践

1. 基础组件开发

选项式 API + TypeScript

组合式 API + <script setup>

2. 高级类型应用

接口定义复杂数据结构

泛型实现可复用逻辑

装饰器模式（Vue Class Component）

三、Vuex 4 与 TypeScript 的深度集成

1. 定义 Store 类型

2. 创建类型安全的 Store

3. 在组件中使用 Store

四、VUE3 模板中使用 TS 的方案

1. 使用 as 进行类型断言（不推荐）

2. 通过计算属性或方法处理类型

3. 模板中的类型安全实践

4. 使用 satisfies 验证表达式类型（Vue 3.3+）

五、常见问题与解决方案

1. 如何处理 Vue 单文件组件中的 .vue 类型声明？

2. 如何解决第三方库的类型缺失问题？

3. 如何优化 TypeScript 编译性能？

六、总结

2. 核心配置文件 `tsconfig.json`

组合式 API + `<script setup>`

1. 使用 `as` 进行类型断言（不推荐）

4. 使用 `satisfies` 验证表达式类型（Vue 3.3+）

1. 如何处理 Vue 单文件组件中的 `.vue` 类型声明？