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

各位靓仔靓女们，晚上好！我是你们今晚的TypeScript小喇叭，很高兴能在这里跟大家聊聊Vue 3世界里那位默默耕耘的英雄 – vue-tsc。咱们今天就来扒一扒它的底裤，看看它到底是怎么帮我们搞定类型检查，又如何神奇地生成声明文件。

开场白：为何我们需要 vue-tsc？

想象一下，你写了一大堆Vue组件，里面充满了各种花里胡哨的类型定义。如果没有人帮你检查这些类型是否正确，那就像在黑暗中开车，指不定哪天就撞到南墙了。更糟糕的是，如果你想把你的组件库分享给别人，别人怎么知道你的组件有哪些属性，类型是什么呢？手动写文档？太low了！

这时候，vue-tsc就闪亮登场了。它是Vue官方提供的 TypeScript 命令行工具，基于 TypeScript 编译器 (tsc) 构建，专门为 Vue 项目量身定制。简单来说，它负责两件大事：

类型检查 (Type Checking): 确保你的Vue代码，包括.vue单文件组件和.ts文件，符合TypeScript的类型规范，提前发现潜在的类型错误。
声明文件生成 (.d.ts Generation): 为你的Vue组件和模块生成声明文件，方便其他开发者在使用你的组件库时获得更好的类型提示和自动补全。

说白了，vue-tsc就是Vue项目里的类型保镖兼文档小秘书。

vue-tsc 的工作原理：一场 TypeScript 的盛宴

vue-tsc 本质上是对 tsc 的一个封装，所以理解 tsc 的工作原理是关键。 tsc 的工作流程大概是这样的：

读取 tsconfig.json: 这是 TypeScript 项目的配置文件，里面定义了各种编译选项，比如要包含哪些文件，使用哪个 TypeScript 版本，目标 JavaScript 版本等等。
解析文件: tsc 会根据 tsconfig.json 中 include 和 exclude 配置，找到需要编译的 TypeScript 文件（包括.ts 和 .vue 文件，后者由 Vue 的 TypeScript 插件处理）。
类型检查: tsc 会对所有文件进行类型检查，确保代码符合类型规范。如果发现类型错误，会报错并停止编译 (除非配置了 noEmitOnError: false)。
代码转换 (Transpilation): 将 TypeScript 代码转换为指定版本的 JavaScript 代码。
生成声明文件: 如果配置了 declaration: true，tsc 会根据 TypeScript 代码生成对应的声明文件 (.d.ts)。

vue-tsc 在这个流程中主要做了两件事：

Vue 组件的类型支持: 它使用了 Vue 官方提供的 TypeScript 插件 (@vue/compiler-sfc)，能够解析 .vue 文件，提取出 template、script 和 style 部分，并对 script 部分进行类型检查。这个插件会将 template 转换为 TypeScript 代码，并与 script 部分的代码进行类型推断和检查，确保 template 中使用的变量和类型与 script 中定义的匹配。
更好的错误信息: vue-tsc 会对 tsc 输出的错误信息进行优化，使其更易于理解和定位。

实战演练：手把手教你玩转 vue-tsc

光说不练假把式，咱们来实际操作一下，看看 vue-tsc 到底是怎么工作的。

1. 项目初始化

首先，我们需要一个 Vue 3 + TypeScript 的项目。如果你还没有，可以使用 Vue CLI 快速创建一个：

vue create my-vue-ts-project
# 选择 Vue 3 预设，并勾选 TypeScript

或者使用 Vite：

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

2. 配置 tsconfig.json

打开项目根目录下的 tsconfig.json 文件，确保以下配置：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "declaration": true, // 开启声明文件生成
    "declarationDir": "./dist/types", // 声明文件输出目录
    "types": ["vite/client"] // 解决 vite 里的模块引入问题
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

重点关注以下几个配置项：

strict: true: 开启严格模式，可以帮助你发现更多的类型错误。
jsx: "preserve": 保留 JSX 语法，让 Vue 3 的 template 编译器处理。
declaration: true: 开启声明文件生成。
declarationDir: 指定声明文件的输出目录。
include: 指定要包含的文件，这里包含了所有的.ts、.tsx 和 .vue 文件。

3. 编写 Vue 组件

创建一个简单的 Vue 组件 src/components/MyComponent.vue：

<template>
  <div>
    <h1>{{ message }}</h1>
    <button @click="increment">Increment</button>
    <p>Count: {{ count }}</p>
  </div>
</template>

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

interface Props {
  initialCount?: number;
  greeting?: string;
}

const props = withDefaults(defineProps<Props>(), {
  initialCount: 0,
  greeting: 'Hello',
});

const count = ref(props.initialCount);
const message = ref(`${props.greeting}, Vue!`);

const increment = () => {
  count.value++;
};

defineExpose({
  count
})
</script>

这个组件定义了一个 initialCount 和 greeting 两个可选的 props，并使用 ref 创建了一个 count 和 message 变量。

4. 运行 vue-tsc

打开终端，运行以下命令：

vue-tsc --noEmit

--noEmit 选项告诉 vue-tsc 只进行类型检查，不生成 JavaScript 文件。如果你的代码有类型错误，vue-tsc 会在终端输出错误信息。

如果一切顺利，你应该会看到类似这样的输出：

✨ No errors found.

5. 生成声明文件

如果你想生成声明文件，可以运行以下命令：

vue-tsc

这次不加 --noEmit，vue-tsc 会进行类型检查并生成 JavaScript 文件和声明文件。

执行完毕后，你会在 tsconfig.json 中配置的 declarationDir 目录（默认为 ./dist/types）下看到生成的声明文件 MyComponent.vue.d.ts。

打开这个文件，你会看到类似这样的内容：

declare const _default: import("vue").DefineComponent<{
    initialCount: {
        type: NumberConstructor;
        required: false;
        default: number;
    };
    greeting: {
        type: StringConstructor;
        required: false;
        default: string;
    };
}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
    initialCount: {
        type: NumberConstructor;
        required: false;
        default: number;
    };
    greeting: {
        type: StringConstructor;
        required: false;
        default: string;
    };
}>>, {
    initialCount: number;
    greeting: string;
}, {}>;
export default _default;

虽然看起来有点复杂，但它包含了 MyComponent.vue 组件的所有类型信息，包括 props 的类型、组件暴露的属性等等。

6. 使用组件库时的类型提示

现在，假设你把这个组件库发布到了 npm 上，其他开发者在使用你的组件时，就可以获得完整的类型提示和自动补全。

例如，在另一个 Vue 项目中引入 MyComponent.vue：

<template>
  <MyComponent :initial-count="10" greeting="Hi" />
</template>

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

当你输入 :initial-count= 时，编辑器会自动提示你 initialCount 的类型是 number。如果你输入了错误的类型，vue-tsc 会报错。

高级用法：更上一层楼

vue-tsc 还有一些高级用法，可以帮助你更好地管理 TypeScript 类型：

自定义类型声明文件: 有时候，vue-tsc 自动生成的声明文件可能不够精确，你需要手动编写类型声明文件。可以在 tsconfig.json 的 include 中包含 .d.ts 文件，让 vue-tsc 识别这些文件。
使用 vue-shim.d.ts: 在 Vue 3 项目中，为了让 TypeScript 识别 .vue 文件，通常需要创建一个 vue-shim.d.ts 文件：
```
declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}
```
这个文件告诉 TypeScript，所有以 .vue 结尾的文件都是 Vue 组件。
与 ESLint 集成: 可以将 vue-tsc 与 ESLint 集成，在代码提交前自动进行类型检查和代码风格检查。这样可以确保代码质量，减少潜在的错误。

常见问题与解决方案

在使用 vue-tsc 的过程中，可能会遇到一些问题。这里列举一些常见的问题和解决方案：

问题	解决方案
`找不到模块“xxx.vue”或其相应的类型声明。`	确保已经创建了 `vue-shim.d.ts` 文件，并且在 `tsconfig.json` 的 `include` 中包含了 `.vue` 文件。
`类型“xxx”不能赋值给类型“yyy”。`	仔细检查类型定义，确保类型匹配。可以使用 TypeScript 的类型推断功能，让 TypeScript 自动推断类型。如果类型确实不匹配，需要修改代码或类型定义。
`vue-tsc 运行缓慢。`	可以尝试以下方法： 1. 减少 `tsconfig.json` 中 `include` 的文件数量。 2. 开启 TypeScript 的增量编译功能 (`incremental: true`)。 3. 使用更快的 TypeScript 编译器 (`esbuild`)。
`声明文件生成不正确。`	检查代码中是否有类型定义错误。可以尝试手动编写类型声明文件，覆盖 `vue-tsc` 自动生成的声明文件。如果使用了第三方库，确保已经安装了该库的类型声明文件 (`@types/xxx`)。
`Vite 项目中类型报错`	确保 `tsconfig.json` 中配置了 `"types": ["vite/client"]`。这可以解决 Vite 提供的全局类型定义问题，例如 `import.meta.env`。如果仍然报错，尝试重启 TypeScript Server 或 VS Code。

总结：拥抱类型，拥抱未来

vue-tsc 是 Vue 3 项目中不可或缺的工具，它可以帮助我们编写更健壮、更易于维护的代码。掌握 vue-tsc 的使用方法，可以让我们在 Vue 3 的世界里更加游刃有余。

记住，类型检查不是负担，而是保障。拥抱类型，拥抱未来！

好了，今天的讲座就到这里。希望大家有所收获，以后写 Vue 代码的时候，别忘了让 vue-tsc 帮你保驾护航！如果有任何问题，欢迎随时提问。拜拜！

发表回复 取消回复

发表回复取消回复