Vite 项目中使用 vite-plugin-dts 插件的详细指南

在现代前端开发中，TypeScript 的类型声明文件（.d.ts）对于提供良好的开发体验和代码提示至关重要。如果你正在使用 Vite 构建一个库项目，vite-plugin-dts 插件是一个非常有用的工具，它可以帮助你自动生成 .d.ts 文件。以下是如何在你的 Vite 项目中安装、配置和使用 vite-plugin-dts 插件的详细指南。

#一、插件介绍

vite-plugin-dts 是一个用于在 Vite 的库模式下，从 .ts(x) 或 .vue 源文件生成类型文件（*.d.ts）的插件。它能够帮助开发者在构建库时，自动生成类型声明文件，从而提高开发效率。

#二、安装插件

在开始之前，你需要先安装 vite-plugin-dts 插件。打开终端，运行以下命令：

复制pnpm i vite-plugin-dts -D

这将把 vite-plugin-dts 添加到你的项目依赖中。

#三、基本配置

安装完成后，你需要在 Vite 的配置文件中引入并配置该插件。以下是一个基本的配置示例：

#1. 修改 vite.config.ts

打开你的 vite.config.ts 文件，添加以下内容：

复制import { resolve } from 'path';
import { defineConfig } from 'vite';
import dts from 'vite-plugin-dts';

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'), 
      name: 'MyLib', 
      formats: ['es'], 
      fileName: 'my-lib' 
    }
  },
  plugins: [dts()] 
});

在这个配置中，build.lib.entry 指定了库的入口文件路径，name 是库的名称，formats 指定了输出的格式，fileName 是输出文件的名称。

#2. 默认行为

默认情况下，vite-plugin-dts 会根据源文件的结构生成 .d.ts 文件。如果你希望将所有的类型合并到一个文件中，可以在插件配置中设置 rollupTypes: true：

复制plugins: [dts({ rollupTypes: true })]

这样，所有的类型声明将会被合并到一个文件中。

#四、高级配置

vite-plugin-dts 提供了许多高级配置选项，可以帮助你更好地控制类型文件的生成。

#1. 指定 tsconfig.json 路径

如果你的项目使用了多个 tsconfig.json 文件，或者你的 tsconfig.json 文件不在项目的根目录下，你可以通过 tsconfigPath 选项指定正确的配置文件路径。例如：

复制plugins: [dts({ tsconfigPath: './tsconfig.app.json' })]

这将告诉插件使用指定的 tsconfig.json 文件来解析类型。

#2. 自定义输出目录

默认情况下，生成的 .d.ts 文件会输出到 Vite 配置中的 build.outDir 目录。如果你需要自定义输出目录，可以使用 outDir 选项：

复制plugins: [dts({ outDir: './dist/types' })]

这将把类型文件输出到 ./dist/types 目录。

#3. 路径别名

如果你的项目中使用了路径别名（如 @/），可以通过 pathsToAliases 选项让插件解析这些别名：

复制plugins: [dts({ pathsToAliases: true })]

这样，生成的 .d.ts 文件中将会使用正确的路径别名。

#4. 类型入口文件

如果你希望生成一个类型入口文件（如 index.d.ts），可以设置 insertTypesEntry: true：

复制plugins: [dts({ insertTypesEntry: true })]

这将基于 package.json 中的 types 字段生成一个入口文件。

#五、常见问题及解决方案

在使用 vite-plugin-dts 时，可能会遇到一些常见的问题。以下是一些常见问题及其解决方案：

#1. 无法从 node_modules 推断类型

如果你在打包时遇到无法从 node_modules 中的包推断类型的错误，这可能是由于 TypeScript 通过软链接（如 pnpm）读取 node_modules 中的类型时出现的问题。可以通过在 tsconfig.json 中添加 baseUrl 和 paths 来解决：

复制{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "third-lib": ["node_modules/third-lib"]
    }
  }
}

#2. 使用 rollupTypes: true 时出现 Internal Error

如果在启用 rollupTypes: true 时出现内部错误，这可能是由于 @microsoft/api-extractor 或 TypeScript 解析器的限制导致的。主要原因是 tsconfig.json 中指定了 baseUrl 并且直接使用了非标准路径。可以通过以下方式解决：

• 避免直接使用非标准路径，改为使用相对路径。
• 使用 paths 配置别名来代替直接路径。

#3. 打包时找不到模块

如果在打包时出现找不到模块的错误，这可能是由于 tsconfig.json 中的 include 配置不正确导致的。确保在 tsconfig.json 中正确配置了 include，或者通过插件的 tsconfigPath 选项指定一个包含正确 include 的配置文件路径。

#4. 打包后类型文件缺失

默认情况下，skipDiagnostics 选项为 true，这意味着在打包过程中会跳过类型检查。如果存在类型错误的文件，并且这些错误中断了打包过程，那么这些文件对应的类型文件将不会被生成。如果项目中没有使用外部的类型检查工具，可以设置 skipDiagnostics: false 和 logDiagnostics: true，以启用插件的诊断和日志功能，帮助检查打包过程中出现的类型错误。

#六、示例项目

为了更好地理解如何使用 vite-plugin-dts，可以参考以下示例项目：

#1. 克隆项目

克隆 vite-plugin-dts 的官方仓库：

复制git clone https://github.com/qmhc/vite-plugin-dts.git

#2. 运行示例

进入项目目录，运行以下命令：

复制pnpm run test:ts

然后检查 examples/ts/types 目录，查看生成的类型文件。

#七、总结

vite-plugin-dts 是一个非常强大的工具，可以帮助你在 Vite 项目中自动生成 .d.ts 文件。通过合理的配置，你可以轻松地生成类型声明文件，从而提高开发效率和代码质量。