深入分析 Vue 3 中的 `vue-tsc` (TypeScript 命令行工具) 如何进行类型检查和生成声明文件 (`.d.ts`)。

各位观众老爷们，今天咱们来聊聊Vue 3里那个负责把TypeScript代码变成靠谱代码的家伙——vue-tsc。它不光能像个老中医一样，给你代码把把脉，看看有没有啥毛病，还能顺手把你的代码整理成一份说明书（也就是声明文件 .d.ts），让别人用你的组件的时候，也能知道该怎么用，不至于瞎猫碰上死耗子。

咱们今天就从头到尾，把vue-tsc扒个精光，看看它到底是怎么干活的。

开场白：为啥我们需要vue-tsc?

首先，为啥我们需要这么个东西？TypeScript 带来的好处不用多说，类型检查让代码更健壮，编辑器提示让开发更高效。但是在 Vue 3 的 SFC (Single File Component) 场景下，事情就变得稍微复杂一点了。

你可能会想，直接用 tsc （TypeScript 编译器）不就得了？理论上是可以的，但问题在于，tsc 默认不认识 .vue 文件。它只认 .ts、.tsx、.js、.jsx 这些。所以我们需要一个工具，能够理解 .vue 文件的结构，并且把里面的 TypeScript 代码提取出来，交给 tsc 去处理。

vue-tsc 就是干这个活的。它是个基于 tsc 的封装，专门用来处理 Vue 3 的 TypeScript 项目。

vue-tsc 的核心功能：

1. 类型检查: 扫描你的项目，找出 TypeScript 代码中的类型错误。
2. 声明文件生成: 根据你的代码，生成 .d.ts 文件，方便其他开发者使用你的组件库或模块。
3. 模板类型推断: 利用 Volar 的能力，进行模板中的类型推断，让你在 .vue 文件的 template 部分也能享受到类型检查的好处。
4. 与 IDE 集成: 和 VS Code、WebStorm 等主流 IDE 配合良好，提供实时类型检查和代码提示。

vue-tsc 工作流程：

简单来说，vue-tsc 的工作流程可以概括为以下几步：

1. 读取配置： 读取 tsconfig.json 文件，获取 TypeScript 编译器的配置信息，例如编译选项、包含的文件等等。
2. 解析 .vue 文件： 遍历项目中的 .vue 文件，解析它们的内容，提取出 <script lang="ts"> 或 <script setup lang="ts"> 标签中的 TypeScript 代码。
3. 类型检查： 将提取出来的 TypeScript 代码交给 tsc 进行类型检查。如果发现错误，会在控制台输出错误信息。
4. 生成声明文件： 如果配置了生成声明文件，vue-tsc 会根据你的代码生成 .d.ts 文件。这些文件描述了你的组件的 API，包括 props、events、methods 等等。

实战演练：一个简单的例子

光说不练假把式，咱们来写个简单的 Vue 组件，然后用 vue-tsc 跑一下，看看效果。

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

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

interface Props {
  initialCount?: number;
}

const props = defineProps<Props>();

const count = ref(props.initialCount || 0);
const message = ref(`Count is: ${count.value}`);

function increment() {
  count.value++;
  message.value = `Count is: ${count.value}`;
}

defineExpose({
  count,
  increment,
});
</script>

这个组件很简单，一个标题显示计数，一个按钮点击增加计数。我们使用了 defineProps 定义了 props 的类型，使用了 defineExpose 暴露了组件的 API。

接下来，我们需要一个 tsconfig.json 文件，告诉 vue-tsc 该怎么编译我们的代码。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "types": ["node"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "declaration": true,  // 开启声明文件生成
    "declarationDir": "./dist/types",  // 声明文件输出目录
    "skipLibCheck": true
  },
  "vueCompilerOptions": {
    "experimentalTemplateCompilerOptions": {
      "isProduction": false
    }
  },
  "include": ["src/**/*", "vite.config.*", "shims-vue.d.ts"],
  "exclude": ["node_modules"]
}

这个 tsconfig.json 文件里，几个关键的配置项：

• declaration: true：这个选项告诉 vue-tsc 生成声明文件。
• declarationDir: "./dist/types"：这个选项指定声明文件的输出目录。
• include: 指定要编译的文件。
• vueCompilerOptions: Vue 特有的编译选项，比如 experimentalTemplateCompilerOptions 可以控制模板编译的一些行为。

现在，我们就可以在命令行里运行 vue-tsc 了。

vue-tsc --noEmit --emitDeclarationOnly

• --noEmit: 告诉 vue-tsc 不要生成 JavaScript 文件，只进行类型检查和生成声明文件。
• --emitDeclarationOnly: 只生成声明文件。

如果一切顺利，vue-tsc 就会在 dist/types 目录下生成一个 .d.ts 文件，描述我们的组件的 API。

vue-tsc 的高级用法：

vue-tsc 的功能远不止于此，它还有很多高级用法，可以帮助我们更好地管理 TypeScript 项目。

1. 增量编译： vue-tsc 支持增量编译，可以大大提高编译速度。增量编译的原理是，vue-tsc 会缓存上次编译的结果，只编译发生变化的文件。要开启增量编译，需要在 tsconfig.json 文件中设置 incremental: true 选项，并且指定 tsBuildInfoFile 选项，用于存储编译缓存。

   {
     "compilerOptions": {
       "incremental": true,
       "tsBuildInfoFile": "./.tsbuildinfo"
     }
   }

2. 与 ESLint 集成： 为了保证代码风格的一致性，我们通常会使用 ESLint 来检查代码。vue-tsc 可以和 ESLint 集成，在编译过程中自动运行 ESLint，检查代码风格。要集成 ESLint，需要安装 @typescript-eslint/eslint-plugin 和 @typescript-eslint/parser 这两个 ESLint 插件，并且在 ESLint 的配置文件中进行配置。

   {
     "extends": [
       "eslint:recommended",
       "plugin:@typescript-eslint/recommended"
     ],
     "parser": "@typescript-eslint/parser",
     "plugins": ["@typescript-eslint"]
   }

3. 自定义类型声明： 有时候，我们需要为一些没有类型声明的第三方库编写类型声明。vue-tsc 支持自定义类型声明，可以在项目中创建一个 shims.d.ts 文件，用于编写自定义类型声明。

   例如，如果我们想为 vue-demi 这个库编写类型声明，可以创建一个 shims-vue-demi.d.ts 文件，内容如下：

   declare module 'vue-demi' {
     export * from 'vue';
     export const isVue2: boolean;
     export const isVue3: boolean;
   }

   然后在 tsconfig.json 文件的 include 选项中包含这个文件。

4. 模板类型推断的配置： Volar 负责 Vue 模板中的类型推断。你需要确保安装了 Volar 插件，并且在 tsconfig.json 中进行配置。通常，vueCompilerOptions 中的设置就足够了。 比如设置experimentalTemplateCompilerOptions 来控制模板编译的行为。

常见问题及解决方案：

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

1. vue-tsc 报错 "Cannot find module ‘vue’"：

   这个问题通常是由于缺少 Vue 的类型声明文件引起的。可以尝试安装 @types/vue 这个包。

   npm install --save-dev @types/vue

2. vue-tsc 报错 "TS2304: Cannot find name ‘defineProps’"：

   这个问题通常是由于 TypeScript 版本过低引起的。defineProps、defineEmits、defineExpose 这些 API 是 Vue 3.0 引入的，需要 TypeScript 4.0 或以上版本才能支持。

   npm install typescript@latest

3. vue-tsc 报错 "Cannot find module or its corresponding type declarations."：

   这个问题通常是由于缺少第三方库的类型声明文件引起的。可以尝试安装对应的 @types/xxx 包。如果找不到对应的类型声明文件，可以尝试自己编写类型声明。

4. 编译速度慢：

   • 开启增量编译。
   • 检查 include 和 exclude 选项，确保只包含必要的文件。
   • 升级 TypeScript 版本。

总结：

vue-tsc 是 Vue 3 项目中不可或缺的工具，它能够帮助我们进行类型检查，生成声明文件，提高代码质量和开发效率。 掌握 vue-tsc 的使用方法，能够让我们更好地驾驭 Vue 3 + TypeScript 这个组合。

希望今天的讲解对大家有所帮助。 记住，代码写得好不好，vue-tsc 说了算！ 咱们下期再见！

表格总结常用命令：

命令	作用
vue-tsc	执行类型检查和声明文件生成，默认读取 tsconfig.json 配置。
vue-tsc --noEmit	只进行类型检查，不生成 JavaScript 文件或声明文件。
vue-tsc --emitDeclarationOnly	只生成声明文件 (.d.ts)，不进行其他编译工作。
vue-tsc -p tsconfig.json	指定 tsconfig.json 文件的路径。当你的 tsconfig.json 文件不在项目根目录时使用。
vue-tsc --watch	监听文件变化，自动进行类型检查和编译。
vue-tsc --project ./path/to/tsconfig.json	指定 tsconfig.json 文件路径，与 -p 相同，但是更明确。
vue-tsc --build	根据 tsconfig.json 中的 references 字段，构建项目及其依赖的项目 (monorepo 场景常用)。
vue-tsc --listFiles	列出 vue-tsc 将要编译的所有文件。
vue-tsc --help	显示 vue-tsc 的帮助信息，列出所有可用的命令行选项。

未来展望：

随着 Vue 和 TypeScript 的不断发展，vue-tsc 也会不断进化。 未来，我们可以期待 vue-tsc 在以下几个方面有所改进：

• 更强大的模板类型推断： 更准确地推断模板中的类型，提供更好的代码提示和错误检查。
• 更快的编译速度： 利用更先进的编译技术，提高编译速度，减少开发等待时间。
• 更友好的错误提示： 提供更清晰、更易于理解的错误提示信息，帮助开发者更快地定位和解决问题。

总而言之，vue-tsc 是我们构建高质量 Vue 3 + TypeScript 应用的得力助手，值得我们深入学习和掌握。