进阶 unplugin.unjs.io 2026-10-08 10:00:35 · 6 阅读

第9章 unplugin-isolated-decl 极速生成 isolated declarations 工具详解

第9章 unplugin-isolated-decl

⚡️ 一个极速生成 isolated declarations 的工具。

特性

- 🚀 快速：生成 .d.ts 文件的速度远超 tsc。 - 🎨 Transformer：支持 Oxc、SWC 和 TypeScript transformer。 - 📦 零配置：无需任何配置，开箱即用。 - ✨ 打包器支持：兼容 Vite、Rollup、esbuild 和 Farm。

提示：如果你使用 Rolldown，推荐使用 rolldown-plugin-dts，功能更强大、更灵活。

安装

```bash # npm npm i -D unplugin-isolated-decl

# jsr npx jsr add -D @unplugin/isolated-decl ```

使用

Vite

```ts // vite.config.ts import UnpluginIsolatedDecl from 'unplugin-isolated-decl/vite'

export default defineConfig({ plugins: [UnpluginIsolatedDecl()], }) ```

Rollup

```ts // rollup.config.js import UnpluginIsolatedDecl from 'unplugin-isolated-decl/rollup'

export default { plugins: [UnpluginIsolatedDecl()], } ```

Rolldown

```ts // rolldown.config.js import UnpluginIsolatedDecl from 'unplugin-isolated-decl/rolldown'

export default { plugins: [UnpluginIsolatedDecl()], } ```

esbuild

```ts // esbuild.config.js import { build } from 'esbuild'

build({ plugins: [require('unplugin-isolated-decl/esbuild')()], }) ```

Farm

```ts // farm.config.ts import UnpluginIsolatedDecl from 'unplugin-isolated-decl/farm'

export default defineConfig({ plugins: [UnpluginIsolatedDecl()], }) ```

配置项

```ts export interface Options { include?: FilterPattern exclude?: FilterPattern enforce?: 'pre' | 'post' | undefined / * 如果不使用 oxc，需要手动安装对应的 transformer。 * swc: @swc/core * typescript: typescript * * @default oxc */ transformer?: 'oxc' | 'swc' | 'typescript' / * 是否生成声明的 source map。 * * 仅 `typescript` 和 `oxc` transformer 支持。 * * @link https://www.typescriptlang.org/tsconfig/#declarationMap */ sourceMap?: boolean

transformOptions?: TranspileOptions ignoreErrors?: boolean / 为输出文件额外增加一层目录。 */ extraOutdir?: string

rewriteImports?: ( id: string, importer: string, ) => string | void | null | undefined } ```

rewriteImports

重写 .d.ts 文件中的导入路径。（esbuild 暂不支持）

以下是在 Rollup 中重写导入的示例：

```js // rollup.config.js import alias from '@rollup/plugin-alias'

export default { // ... plugins: [ alias({ entries: [{ find: '~', replacement: '.' }] }), UnpluginIsolatedDecl({ rewriteImports(id, importer) { if (id[0] === '~') return `.${id.slice(1)}` }, }), // ... ], } ```