第4章 unplugin-auto-import 自动导入插件

3,797217 unplugin-auto-import ​ 为 Vite、Webpack、Rspack、Rollup 和 esbuild 按需自动导入 API，支持 TypeScript，基于 unplugin 构建。 不使用（ts）： import { computed, ref } from 'vue' const count = ref(0) const doubled = computed(() => count.value * 2) 使用（ts）： const count = ref(0) const doubled = computed(() => count.value * 2) 不使用（tsx）： import { useState } from 'react' export function Counter() { const [count, setCount] = useState(0) return } 使用（tsx）： export function Counter() { const [count, setCount] = useState(0) return 安装 ```bash npm i -D unplugin-auto-import ``` Vite ```ts // vite.config.ts import AutoImport from 'unplugin-auto-import/vite' export default defineConfig({ plugins: [ AutoImport({ /* 选项 */ }), ], }) ``` 示例：playground/Rollup ```ts // rollup.config.js import AutoImport from 'unplugin-auto-import/rollup' export default { plugins: [ AutoImport({ /* 选项 */ }), // 其他插件 ], } ``` Rolldown ```ts // rolldown.config.js import AutoImport from 'unplugin-auto-import/rolldown' export default { plugins: [ AutoImport({ /* 选项 */ }), // 其他插件 ], } ``` Webpack ```ts // webpack.config.js module.exports = { /* ... */ plugins: [ require('unplugin-auto-import/webpack')({ /* 选项 */ }), ], } ``` Rspack ```ts // rspack.config.js module.exports = { /* ... */ plugins: [ require('unplugin-auto-import/rspack')({ /* 选项 */ }), ], } ``` Nuxt Nuxt 无需此插件，已内置支持。 Quasar ```ts // vite.config.js [Vite] import AutoImport from 'unplugin-auto-import/vite' import { defineConfig } from 'vite' export default defineConfig({ plugins: [ AutoImport({ /* 选项 */ }) ] }) ``` ```ts // quasar.config.js export default defineConfig(() => { return { build: { vitePlugins: [ ['unplugin-auto-import/vite', { /* 选项 */ }], ] }, } }) ``` esbuild ```ts // esbuild.config.js import { build } from 'esbuild' import AutoImport from 'unplugin-auto-import/esbuild' build({ /* ... */ plugins: [ AutoImport({ /* 选项 */ }), ], }) ``` Astro ```ts // astro.config.mjs import AutoImport from 'unplugin-auto-import/astro' export default defineConfig({ integrations: [ AutoImport({ /* 选项 */ }) ], }) ``` 配置 ```ts AutoImport({ // 要转换的目标 include: [ /\.[tj]sx?$/, // .ts, .tsx, .js, .jsx /\.vue$/, /\.vue\?vue/, // .vue /\.vue\.[tj]sx?\?vue/, // .vue (启用 experimentalInlineMatchResource 的 vue-loader) /\.md$/, // .md ], // 要注册的全局导入 imports: [ // 预设 'vue', 'vue-router', // 自定义 { '@vueuse/core': [ // 命名导入 'useMouse', // import { useMouse } from '@vueuse/core', // 别名 ['useFetch', 'useMyFetch'], // import { useFetch as useMyFetch } from '@vueuse/core', ], 'axios': [ // 默认导入 ['default', 'axios'], // import { default as axios } from 'axios', ], '[包名]': [ '[导入名称]', // 别名 ['[来源]', '[别名]'], ], }, // 类型导入示例 { from: 'vue-router', imports: ['RouteLocationRaw'], type: true, }, ], // 包含需过滤掉的导入的正则表达式字符串数组 ignore: [ 'useMouse', 'useFetch' ], // 启用按文件名自动导入目录下模块的默认导出 defaultExportByFilename: false, // 扫描目录以自动导入的选项 dirsScanOptions: { filePatterns: ['*.ts'], // 用于匹配文件的全局模式 fileFilter: file => file.endsWith('.ts'), // 过滤文件 types: true // 启用目录下类型的自动导入 }, // 目录下模块导出的自动导入 // 默认只扫描目录下第一层级的模块 dirs: [ './hooks', './composables', // 仅根模块 './composables/', // 所有嵌套模块 // ... { glob: './hooks', types: true // 启用类型导入 }, { glob: './composables', types: false // 如果顶层 dirsScanOptions.types 导入已启用，则仅禁用此目录 } // ... ], // 生成对应 .d.ts 文件的路径。 // 如果本地安装了 `typescript`，默认为 './auto-imports.d.ts'。 // 设置为 `false` 以禁用。 dts: './auto-imports.d.ts', // 生成 .d.ts 文件的模式。 // 'overwrite': 用新的类型定义覆盖整个现有的 .d.ts 文件。 // 'append': 仅将新的类型定义追加到现有的 .d.ts 文件，意味着保留现有类型定义。 // 默认为 'append' dtsMode: 'append', // 在生成的 .d.ts 文件中保留原始文件扩展名。 // 设置为 `true` 以保留 .ts 和 .tsx 文件的扩展名。 // 默认为 false dtsPreserveExts: false, // 包含在声明文件生成期间需忽略的导入的正则表达式字符串数组。 // 当你需要为函数提供自定义签名时，这可能很有用。 ignoreDts: [ 'ignoredFunction', /^ignore_/ ], // 在 Vue 模板中自动导入 // 参见 https://github.com/unjs/unimport/pull/15 和 https://github.com/unjs/unimport/pull/72 vueTemplate: false, // 在 Vue 模板中自动导入指令 // 参见 https://github.com/unjs/unimport/pull/374 vueDirectives: undefined, // 自定义解析器，兼容 `unplugin-vue-components` // 参见 https://github.com/antfu/unplugin-auto-import/pull/23/ resolvers: [ /* ... */ ], // 将自动导入的包包含在 Vite 的 `optimizeDeps` 选项中 // 建议启用 viteOptimizeDeps: true, // 将导入注入到其他导入的末尾 injectAtEnd: true, // 生成对应的 .eslintrc-auto-import.json 文件。 // eslint 全局变量文档 - https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals eslintrc: { enabled: false, // 默认 `false` // 提供以 `.mjs` 或 `.cjs` 结尾的路径，以相应格式生成文件 filepath: './.eslintrc-auto-import.json', // 默认 `./.eslintrc-auto-import.json` globalsPropValue: true, // 默认 `true`，(true | false | 'readonly' | 'readable' | 'writable' | 'writeable') }, // 生成对应的 .biomelintrc-auto-import.json 文件。 // biomejs extends 文档 - https://biomejs.dev/guides/how-biome-works/#the-extends-option biomelintrc: { enabled: false, // 默认 `false` filepath: './.biomelintrc-auto-import.json', // 默认 `./.biomelintrc-auto-import.json` }, // 将 unimport 项保存为 JSON 文件，供其他工具使用 dumpUnimportItems: './auto-imports.json', // 默认 `false` }) ``` 更多选项请参考类型定义。 预设 参见 src/presets。 包预设 我们只为最热门的包提供预设。要使用此处未包含的任意包，你可以将其安装为开发依赖，并将其添加到 `packagePresets` 数组选项： ```ts AutoImport({ /* 其他选项 */ packagePresets: ['detect-browser-es' /* 其他本地包名 */] }) ``` 你可以参考 Svelte 示例，查看注册 detect-browser-es 包预设并在 App.svelte 中自动导入 detect 函数的实际案例。 关于 ignore 或 cache 等选项的更多信息，请参见 unimport 的 PackagePresets jsdocs。 注意：确保使用的本地包正确配置了 package exports，否则无法检测到相应的模块导出。 TypeScript 为了正确提示自动导入 API 的类型： 1. 启用 `options.dts`，使 `auto-imports.d.ts` 文件自动生成 2. 确保 `auto-imports.d.ts` 未在 `tsconfig.json` 中被排除
tsAutoImport({ dts: true // 或自定义路径 })为了更好地支持在自动导入 API 时进行代码导航，建议使用 @dxup/unimport 包。ESLint 💡 使用 TypeScript 时，建议直接禁用 no-undef 规则，因为 TypeScript 本身就会检查这些内容，无需再担心此问题。如果遇到 ESLint 的 no-undef 错误：启用 eslintrc.enabled
tsAutoImport({ eslintrc: { enabled: true, // <-- 此处 }, })更新你的 eslintrc：扩展配置文件
ts// .eslintrc.js module.exports = { extends: [ './.eslintrc-auto-import.json', ], }常见问题 ​与 unimport 的对比 ​从 v0.8.0 版本开始，unplugin-auto-import 底层使用 unimport。unimport 被设计为更底层的工具（它也驱动了 Nuxt 的自动导入功能）。你可以将 unplugin-auto-import 视为 unimport 的封装，它提供了更友好的配置 API 以及解析器等能力。未来的新功能开发将主要发生在 unimport 中。与 vue-global-api 的对比 ​可以将此插件视为 vue-global-api 的继任者，但它提供了更大的灵活性，并支持 Vue 以外的库（如 React）。优势 ​灵活且可定制支持 Tree-shaking（按需转换）无需污染全局命名空间劣势 ​依赖构建工具集成（而 vue-global-api 是纯运行时方案）——不过我们已经支持了不少构建工具！赞助商 ​许可证 ​MIT License © 2021-PRESENT Anthony Fu