unplugin-dts完整指南：从vite-plugin-dts迁移到通用插件

unplugin-dts完整指南：从vite-plugin-dts迁移到通用插件

【免费下载链接】unplugin-dtsAn unplugin for generating declaration (dts) files.项目地址: https://gitcode.com/gh_mirrors/vi/unplugin-dts

unplugin-dts是一款功能强大的通用插件，用于生成TypeScript声明文件（*.d.ts），支持Vite、Rollup、Rolldown、Webpack、Rspack和Esbuild等多种构建工具。它是vite-plugin-dts的升级版，将核心逻辑提取为独立的unplugin，同时保持vite-plugin-dts作为兼容性层存在。

为什么选择unplugin-dts？

unplugin-dts带来了多项重要改进，使其成为生成TypeScript声明文件的理想选择：

• 多构建工具支持：不再局限于Vite，现在可以在Rollup、Rolldown、Webpack、Rspack和Esbuild中使用
• 更强大的配置选项：提供了更灵活的输出目录配置、自定义路径别名等功能
• 优化的性能：内部重构带来了更好的性能表现
• 更好的Vue支持：改进了Vue文件的类型处理

安装与基本配置

安装步骤

根据你的项目类型，选择合适的安装命令：

# Vite项目（兼容性模式，仍可使用vite-plugin-dts） pnpm i -D vite-plugin-dts # Vite项目（推荐，直接使用unplugin-dts） pnpm i -D unplugin-dts # Rollup/Rolldown/Webpack/Rspack/Esbuild项目 pnpm i -D unplugin-dts # 使用bundleTypes功能时 pnpm i -D @microsoft/api-extractor # Vue项目 pnpm i -D @vue/language-core

基本配置示例

不同构建工具的导入方式略有不同：

// Vite import dts from 'unplugin-dts/vite' // Rollup import dts from 'unplugin-dts/rollup' // Rolldown import dts from 'unplugin-dts/rolldown' // Webpack import dts from 'unplugin-dts/webpack' // Rspack import dts from 'unplugin-dts/rspack' // Esbuild import dts from 'unplugin-dts/esbuild' // 配置示例（以Vite为例） export default defineConfig({ plugins: [dts()] })

从vite-plugin-dts迁移的关键变化

包导入路径变更

vite-plugin-dts v4与unplugin-dts v5的导入方式对比：

// v4 (vite-plugin-dts) import dts from 'vite-plugin-dts' // v5 (兼容模式，仍可使用) import dts from 'vite-plugin-dts' // v5 (推荐，直接使用unplugin-dts) import dts from 'unplugin-dts/vite'

配置选项变化

最主要的变化是rollupTypes重命名为bundleTypes，并将相关配置项整合：

// v4 dts({ rollupTypes: true, bundledPackages: ['vue'], rollupConfig: { /* ... */ }, rollupOptions: { /* ... */ }, outDir: 'dist' }) // v5 dts({ bundleTypes: { bundledPackages: ['vue'], extractorConfig: { /* ... */ }, // 原rollupConfig invokeOptions: { /* ... */ }, // 原rollupOptions configPath: './api-extractor.json' // 新增配置文件路径 }, outDirs: 'dist' // 原outDir重命名为outDirs })

outDirs的增强功能

v5的outDirs支持更丰富的配置，可以指定多个输出目录和模块格式：

dts({ outDirs: [ 'dist', // 默认生成.d.ts文件 { dir: 'dist-cjs', moduleFormat: 'cjs' }, // 生成.d.cts文件 { dir: 'dist-esm', moduleFormat: 'esm' } // 生成.d.mts文件 ] })

新增的processor选项

v5引入了processor选项来控制TypeScript程序的创建方式：

dts({ processor: 'vue' // 或'ts'（默认） })

• 未指定时，插件会自动检测源文件中是否有.vue文件，如有则自动使用'vue'处理器
• 纯TypeScript项目保持默认的'ts'即可
• Vue项目需要单独安装@vue/language-core

自定义路径别名

除了从tsconfig.json自动解析别名外，v5还允许直接传递自定义别名：

dts({ aliases: [ { find: /^@\//, replacement: './src/' }, { find: 'old-pkg', replacement: 'new-pkg' } ] })

迁移步骤与示例

步骤1：安装新依赖

# 卸载旧版vite-plugin-dts（如已安装） pnpm remove vite-plugin-dts # 安装unplugin-dts pnpm i -D unplugin-dts # 如果使用bundleTypes功能 pnpm i -D @microsoft/api-extractor # 如果是Vue项目 pnpm i -D @vue/language-core

步骤2：更新导入路径

// vite.config.ts // 从 import dts from 'vite-plugin-dts' // 改为 import dts from 'unplugin-dts/vite'

步骤3：更新配置选项

// vite.config.ts export default defineConfig({ plugins: [ dts({ // 替换 rollupTypes: true 为 bundleTypes: true, // 替换 outDir: 'dist' 为 outDirs: 'dist', // 如果有自定义rollup配置 bundleTypes: { // 替换 rollupConfig 为 extractorConfig extractorConfig: { /* ... */ }, // 替换 rollupOptions 为 invokeOptions invokeOptions: { /* ... */ }, // 可选：添加配置文件路径 configPath: './api-extractor.json' }, // 移除 logLevel 选项 // logLevel: 'info' // v4的选项，v5已移除 }) ] })

完整迁移示例

Vite项目迁移

// vite.config.ts (迁移前) import { defineConfig } from 'vite' import dts from 'vite-plugin-dts' export default defineConfig({ plugins: [ dts({ rollupTypes: true, rollupConfig: { // 一些rollup配置 }, outDir: 'dist', logLevel: 'info' }) ] }) // vite.config.ts (迁移后) import { defineConfig } from 'vite' import dts from 'unplugin-dts/vite' export default defineConfig({ plugins: [ dts({ bundleTypes: { extractorConfig: { // 一些rollup配置 } }, outDirs: 'dist' }) ] })

Rollup项目迁移

// rollup.config.mjs (迁移后) import typescript from '@rollup/plugin-typescript' import dts from 'unplugin-dts/rollup' export default { input: './src/index.ts', output: { dir: 'dist', format: 'esm' }, plugins: [ typescript(), dts({ bundleTypes: true, outDirs: 'dist' }) ] }

常见问题与解决方案

问题1：Vue项目类型生成不正确

解决方案：确保安装了@vue/language-core并显式设置processor：

dts({ processor: 'vue' })

问题2：声明文件未复制到输出目录

解决方案：v5中copyDtsFiles选项的默认值因构建工具而异，如遇问题可显式设置：

dts({ copyDtsFiles: true // 显式启用复制 })

问题3：找不到@microsoft/api-extractor

解决方案：使用bundleTypes功能时需要手动安装：

pnpm i -D @microsoft/api-extractor

总结

unplugin-dts作为vite-plugin-dts的升级版，带来了多构建工具支持、更强大的配置选项和更好的性能。迁移过程主要涉及包安装、导入路径更新和配置选项调整。通过本文档的指南，你可以轻松完成从vite-plugin-dts到unplugin-dts的迁移，并充分利用其新特性。

更多详细信息，请参考官方文档：

• 使用说明
• 配置选项
• 常见问题
• 迁移指南

【免费下载链接】unplugin-dtsAn unplugin for generating declaration (dts) files.项目地址: https://gitcode.com/gh_mirrors/vi/unplugin-dts