深入分析 Vue 3 中的 `vue-tsc` (TypeScript 命令行工具) 如何进行类型检查和生成声明文件 (`.d.ts`)。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

大家好，各位靓仔靓女，我是你们的老朋友 bug 终结者，今天咱们来聊聊 Vue 3 里面的 vue-tsc，这玩意儿可以算是 TypeScript 界的 Vue 3 好帮手，专门负责类型检查和生成声明文件。别看名字有点像外星语，其实搞懂了原理，用起来那是相当顺手的。

咱们今天就来好好剖析一下 vue-tsc 到底是怎么工作的，就像解剖一只青蛙，不对，是解剖一个框架，一步一步来，保证大家听得懂，学得会。

第一部分：vue-tsc 是个啥？它为啥这么重要？

首先，vue-tsc 顾名思义，就是 Vue 版本的 tsc。 tsc 是 TypeScript 编译器自带的命令行工具，负责把 TypeScript 代码编译成 JavaScript 代码。而 vue-tsc 则是在 tsc 的基础上，针对 Vue 单文件组件（.vue 文件）做了优化，让它能够更好地理解 Vue 的语法，进行更精确的类型检查。

想象一下，如果没有 vue-tsc，你直接用 tsc 去编译 .vue 文件，就会发现一堆错误，因为 tsc 不知道 <template> 里面那些花里胡哨的语法是啥意思。 vue-tsc 就像一个翻译官，它能把 .vue 文件里面的 TypeScript 代码翻译成 tsc 能够理解的语言，然后让 tsc 去做类型检查和编译。

为什么要用 vue-tsc 呢？

类型安全： TypeScript 的核心价值就是类型安全。 vue-tsc 能够帮助你在开发阶段就发现类型错误，避免运行时出现一些莫名其妙的 bug。提前发现问题，总比上线了才发现问题要好得多，对吧？
代码提示： 配合 IDE， vue-tsc 能够提供更准确的代码提示，提高开发效率。比如，你在组件里面定义了一个 props， vue-tsc 就能知道这个 props 的类型，然后在你使用这个 props 的时候，给出相应的提示。
生成声明文件： vue-tsc 能够生成 .d.ts 声明文件，方便其他开发者使用你的组件。声明文件就像一份组件的说明书，告诉别人你的组件有哪些 props，有哪些 methods，等等。

第二部分：vue-tsc 的工作原理：一层一层剥开它的心

vue-tsc 的工作流程大致可以分为以下几个步骤：

解析 .vue 文件： vue-tsc 首先会解析 .vue 文件，把里面的 <template>、<script> 和 <style> 标签提取出来。
处理 <template> 标签： 对于 <template> 标签， vue-tsc 会使用 Vue 的模板编译器，把模板代码转换成 JavaScript 代码。这个过程涉及到虚拟 DOM 的概念，这里我们先不深入讨论。
处理 <script> 标签： 对于 <script> 标签， vue-tsc 会把里面的 TypeScript 代码交给 tsc 去处理。注意， vue-tsc 会在把代码交给 tsc 之前，做一些预处理，比如添加一些类型声明，让 tsc 能够更好地理解 Vue 的语法。
类型检查： tsc 会对 TypeScript 代码进行类型检查，如果发现类型错误，就会报错。
生成 JavaScript 代码： 如果类型检查通过， tsc 就会把 TypeScript 代码编译成 JavaScript 代码。
生成声明文件： tsc 还会根据 TypeScript 代码生成 .d.ts 声明文件。

可以用表格来简单概括一下：

步骤	描述	涉及的技术
解析 `.vue` 文件	将 `.vue` 文件分解成 `<template>`、`<script>` 和 `<style>` 三个部分。	正则表达式、文件读取
处理 `<template>`	将 `<template>` 中的 Vue 模板语法转换为 JavaScript 代码，以便后续的类型检查和编译。	Vue 模板编译器（例如 `@vue/compiler-dom` 或 `@vue/compiler-sfc`）、虚拟 DOM
处理 `<script>`	将 `<script>` 中的 TypeScript 代码提取出来，并进行必要的预处理，例如添加类型声明，以便 `tsc` 能够正确地理解 Vue 的语法。	TypeScript 编译器 API、AST (抽象语法树) 操作
类型检查	使用 `tsc` 对处理后的 TypeScript 代码进行类型检查，确保代码符合类型规范。	TypeScript 编译器
生成 JavaScript 代码	如果类型检查通过，则使用 `tsc` 将 TypeScript 代码编译成 JavaScript 代码。	TypeScript 编译器
生成声明文件	使用 `tsc` 根据 TypeScript 代码生成 `.d.ts` 声明文件，以便其他开发者使用你的组件时能够获得类型提示和类型检查。	TypeScript 编译器

第三部分：代码示例：让理论落地

光说不练假把式，咱们来看几个实际的例子。

例子 1：简单的组件类型检查

假设我们有一个简单的组件 MyComponent.vue：

<template>
  <div>
    {{ message }}
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const message = ref<string>('Hello, Vue 3!');
</script>

在这个例子中，我们定义了一个 message 变量，它的类型是 string。如果我们尝试把 message 的值改成一个数字， vue-tsc 就会报错：

<template>
  <div>
    {{ message }}
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const message = ref<number>('Hello, Vue 3!'); // 错误：不能将类型“string”分配给类型“number”。
</script>

例子 2：组件 props 的类型检查

假设我们有一个组件 MyComponent.vue，它接收一个 name 类型的 props：

<template>
  <div>
    Hello, {{ name }}!
  </div>
</template>

<script setup lang="ts">
import { defineProps } from 'vue';

const props = defineProps<{
  name: string;
}>();
</script>

在这个例子中，我们使用 defineProps 定义了一个 name 类型的 props，它的类型是 string。如果我们在使用这个组件的时候，传递一个数字作为 name 的值， vue-tsc 就会报错：

<template>
  <MyComponent :name="123" /> // 错误：类型“number”的参数不能赋给类型“string”的参数。
</template>

<script setup lang="ts">
import MyComponent from './MyComponent.vue';
</script>

例子 3：生成声明文件

假设我们有一个组件 MyComponent.vue：

<template>
  <div>
    Hello, {{ name }}!
  </div>
</template>

<script setup lang="ts">
import { defineProps } from 'vue';

const props = defineProps<{
  name: string;
}>();
</script>

当我们运行 vue-tsc --declaration 命令时， vue-tsc 会生成一个 MyComponent.d.ts 文件，它的内容如下：

declare const _default: import("vue").DefineComponent<{
    name: {
        type: import("vue").PropType<string>;
        required: true;
    };
}, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
    name: {
        type: import("vue").PropType<string>;
        required: true;
    };
}>>, {}>;
export default _default;

这个声明文件告诉我们， MyComponent 组件接收一个 name 类型的 props，它的类型是 string，并且是必须的。其他开发者在使用 MyComponent 组件的时候，就可以根据这个声明文件来了解组件的用法。

第四部分：vue-tsc 的配置：让它更懂你

vue-tsc 的行为可以通过 tsconfig.json 文件来配置。 tsconfig.json 文件是 TypeScript 项目的配置文件，它里面可以配置很多选项，比如：

compilerOptions：配置 TypeScript 编译器的行为，比如目标 JavaScript 版本、模块化方式等等。
include：指定要编译的文件。
exclude：指定要排除编译的文件。

下面是一个简单的 tsconfig.json 文件的例子：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

在这个例子中，我们配置了 TypeScript 编译器的目标 JavaScript 版本是 esnext，模块化方式是 esnext，并且启用了严格模式。我们还指定了要编译的文件是 src 目录下的所有文件，并且排除了 node_modules 目录。

对于 Vue 3 项目，有一些特殊的配置项需要注意：

jsx：必须设置为 "preserve"，否则 vue-tsc 无法正确处理 <template> 标签。
allowJs：可以设置为 true，允许在 TypeScript 项目中使用 JavaScript 文件。
baseUrl 和 paths：可以用来配置模块解析，方便你使用别名导入模块。

第五部分：高级用法：让 vue-tsc 飞起来

除了基本的类型检查和生成声明文件之外， vue-tsc 还有一些高级用法，可以让你更好地利用 TypeScript 的优势。

使用 vue-shim.d.ts 文件： 在 TypeScript 项目中，如果你的组件使用了全局组件或者指令，你需要创建一个 vue-shim.d.ts 文件，来告诉 TypeScript 这些全局组件或者指令的类型。比如，如果你使用了 vue-router，你需要在 vue-shim.d.ts 文件中添加以下内容：
```
import { ComponentCustomProperties } from 'vue'
import { Router } from 'vue-router'

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties {
    $router: Router
  }
}
```
使用类型推断： TypeScript 具有强大的类型推断能力，可以根据代码自动推断出变量的类型。在 Vue 3 中，我们可以利用类型推断来简化代码，减少类型声明。比如，我们可以这样定义一个 props：
```
import { defineProps } from 'vue';

const props = defineProps({
  name: {
    type: String,
    required: true,
  },
});
```
在这个例子中，我们没有显式地指定 props 的类型，但是 TypeScript 仍然能够根据 type 属性推断出 name 的类型是 string。
利用 Volar 插件: Volar 是一个专为 Vue 3 打造的 IDE 扩展，它可以提供更强大的类型检查、代码提示和自动补全功能。配合 Volar 使用 vue-tsc，可以让你在开发 Vue 3 项目时更加得心应手。 Volar 内部集成了 vue-tsc，所以你不需要手动运行 vue-tsc 命令，Volar 会自动在后台进行类型检查。

第六部分：常见问题及解决方案：避坑指南

在使用 vue-tsc 的过程中，你可能会遇到一些问题，下面是一些常见的问题及解决方案：

类型错误： 如果 vue-tsc 报错，你需要仔细检查你的代码，看看是否存在类型错误。可以尝试使用 TypeScript 的类型提示功能，来帮助你找到错误。
模块解析错误： 如果 vue-tsc 提示模块解析错误，你需要检查你的 tsconfig.json 文件，看看是否配置了正确的 baseUrl 和 paths。
声明文件生成错误： 如果 vue-tsc 生成的声明文件不正确，你需要检查你的代码，看看是否缺少类型声明。可以尝试使用 TypeScript 的类型推断功能，来帮助你生成正确的声明文件。
Volar 冲突： 有时候 Volar 可能会因为缓存问题导致类型检查不正确，可以尝试重启 VS Code 或者清除 Volar 的缓存。

总结：vue-tsc，你值得拥有

总的来说， vue-tsc 是一个非常强大的工具，它可以帮助你在开发 Vue 3 项目时，更好地利用 TypeScript 的优势，提高代码质量和开发效率。虽然学习 vue-tsc 需要一些时间和精力，但是一旦你掌握了它的用法，你就会发现它真的是一个神器。

好了，今天的讲座就到这里，希望大家能够有所收获。记住，编程的道路是漫长的，需要不断学习和实践。祝大家早日成为 Vue 3 大佬！

发表回复 取消回复

发表回复取消回复