Vite插件v1.1.0发布：自动导入全面重构

PedroQue992026-07-29 10:01

版本：1.1.0 | 协议：MIT | 依赖：Vite >=5.0.0 <8.0.0

写在前面

v1.1.0 的主题是：autoImport 插件全面重构。

对自动导入插件进行了从底层到 API 的全面重构，新增预设系统、多种导入形式、Lint 配置生成、缓存机制等核心能力，同时在目录扫描和 DTS 生成上做了增强。同时清理了旧版兼容类型（ImportMapping、ResolvedImport），统一为更灵活的 ImportInline 类型体系。

本版重点：

能力 一句话说明 你需要做什么
内置预设系统 imports: ['vue', 'vue-router', 'pinia'] 一键配置 替换手动列举 API 的写法
别名/类型/命名空间导入 支持 as 别名、import type、import * 等全形式 按需使用新格式
ESLint/Biome 配置生成 自动生成 globals 配置，解决 no-undef 报错 开启 eslintrc 或 biomelintrc
HMR 热更新 扫描目录文件变更自动刷新映射表 无需配置，自动生效
缓存机制 缓存预设解析与文件扫描结果，提升构建性能 默认启用
旧版类型清理 移除 ImportMapping、ResolvedImport 等废弃类型 迁移到新类型（见升级指南）

升级方式 ：修改 devDependencies 中版本号为 ^1.1.0。有少量 Breaking Change（仅影响使用了废弃类型的用户）。

一、5 分钟快速上手

1.1 安装与升级

json 复制代码 
{
	"devDependencies": {
		"@meng-xi/vite-plugin": "^1.1.0"
	}
}

1.2 预设快速配置

typescript 复制代码 
// vite.config.ts
import { defineConfig } from 'vite'
import { autoImport } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		// 1.0.0：手动列举每个 API
		// autoImport({ imports: { vue: ['ref', 'reactive', 'computed', 'watch', ...] } })

		// 1.1.0：使用内置预设，一行搞定
		autoImport({
			imports: ['vue', 'vue-router', 'pinia'],
			dts: 'src/auto-imports.d.ts',
			vueTemplate: true
		})
	]
})

1.3 新增导入形式

typescript 复制代码 
autoImport({
	imports: [
		// 预设字符串
		'vue',

		// 别名导入：import { useFetch as useMyFetch } from '@vueuse/core'
		{ '@vueuse/core': ['useMouse', ['useFetch', 'useMyFetch']] },

		// 类型导入：import type { RouteLocationRaw } from 'vue-router'
		{ from: 'vue-router', imports: ['RouteLocationRaw'], type: true },

		// 命名空间导入：import * as _ from 'lodash'
		{ lodash: [['*', '_']] },

		// export assignment 导入：import browser from 'webextension-polyfill'
		{ 'webextension-polyfill': [['=', 'browser']] }
	]
})

二、Breaking Changes 与迁移指南

2.1 移除的废弃类型

移除项 替代方案 影响范围
ImportMapping 类型 使用 InlineImportConfig 或预设字符串 使用该类型的用户
ResolvedImport 类型 使用 ImportInline 使用该类型的用户
AutoImportOptions.fileFilter 使用 include / exclude 或 dirsScanOptions.fileFilter 使用该选项的用户
helpers/compat.ts 兼容模块 无需替代，旧格式不再支持 极少数直接引用

2.2 迁移示例

typescript 复制代码 
// ❌ 1.0.0 旧写法（不再支持）
autoImport({
	imports: [{ module: 'vue', names: ['ref', 'reactive'], defaultImport: false }],
	fileFilter: /\.[tj]sx?$/
})

// ✅ 1.1.0 新写法
autoImport({
	imports: [
		'vue' // 或 { vue: ['ref', 'reactive'] }
	],
	include: [/\.[tj]sx?$/]
})

2.3 兼容性说明

  • imports: { vue: ['ref', 'reactive'] } Record 格式：仍支持，无需修改
  • imports: { vue: ['*'] } 通配符格式：仍支持 ，但推荐使用预设 'vue'
  • dirs 字符串数组格式：仍支持，无需修改
  • dts 字符串/boolean 格式：仍支持，新增 DtsConfig 对象格式

三、新增功能详解

3.1 内置预设系统

通过预设字符串一键启用常用库的自动导入，无需逐一列举 API：

预设名 模块 覆盖 API 数量 示例
vue vue 30+ ref、reactive、computed、watch、onMounted...
vue-router vue-router 15+ useRouter、useRoute、RouterLink...
pinia pinia 8+ defineStore、storeToRefs、createPinia...
vue-i18n vue-i18n 6+ useI18n、createI18n...
typescript 复制代码 
// 预设字符串
autoImport({ imports: ['vue', 'vue-router', 'pinia'] })

// 预设与自定义混合
autoImport({ imports: ['vue', { '@vueuse/core': ['useMouse'] }] })

3.2 多种导入形式

导入形式 配置格式 生成语句
命名导入 { vue: ['ref'] } import { ref } from 'vue'
别名导入 { vue: [['ref', 'refVal']] } import { ref as refVal } from 'vue'
默认导入 { axios: [['default', 'axios']] } import { default as axios } from 'axios'
类型导入 { from: 'vue', imports: ['Ref'], type: true } import type { Ref } from 'vue'
命名空间导入 { lodash: [['*', '_']] } import * as _ from 'lodash'
export assignment { 'webext-polyfill': [['=', 'browser']] } import browser from 'webextension-polyfill'

3.3 目录扫描增强

typescript 复制代码 
autoImport({
	dirs: [
		'./composables', // 仅扫描一级
		'./composables/**', // 递归扫描所有子目录
		{ glob: './hooks', types: true } // DirConfigObject，标记为类型导入
	],
	dirsScanOptions: {
		filePatterns: ['*.ts'], // Glob 文件匹配模式
		fileFilter: file => !file.endsWith('.test.ts'), // 自定义过滤
		types: false // 全局默认类型标记
	}
})

3.4 DTS 生成增强

typescript 复制代码 
autoImport({
	dts: {
		filepath: 'src/auto-imports.d.ts',
		mode: 'append' // 'append' 仅追加新类型 | 'overwrite' 全量覆盖
	},
	dtsPreserveExts: false, // DTS 中是否保留文件扩展名
	ignoreDts: ['React'] // DTS 中排除指定标识符
})

3.5 ESLint / Biome 配置生成

解决自动导入标识符的 no-undef 报错：

typescript 复制代码 
autoImport({
	imports: ['vue'],
	eslintrc: {
		enabled: true,
		filepath: './.eslintrc-auto-import.json',
		globalsPropValue: true // true = true | 'readonly' | 'writable'
	},
	biomelintrc: {
		enabled: true,
		filepath: './biome-auto-import.json'
	}
})

3.6 Vue 指令自动导入

typescript 复制代码 
autoImport({
	imports: ['vue'],
	vueDirectives: {
		enabled: true,
		isDirective: fromPath => fromPath.includes('/directives/')
	}
})

3.7 其他新增功能

功能 配置 说明
缓存机制 cache: true（默认） 缓存预设解析与文件扫描结果，提升构建性能
HMR 热更新 自动启用 扫描目录文件变更时自动重新初始化映射表
注释禁用 // @unimport-disable 文件级或行级禁用自动导入
自定义 Resolver resolvers: [myResolver] 对未命中标识符自定义解析逻辑
包预设 packagePresets: ['@vueuse/core'] 从已安装包的 .d.ts 自动发现导出
Vite optimizeDeps 集成 viteOptimizeDeps: true 自动将依赖加入 Vite 预优化列表（默认关闭）
默认导出按文件名 defaultExportByFilename: true 目录扫描时默认导出使用文件名作为标识符

四、重构优化

优化项 1.0.0 1.1.0
Resolver 回退逻辑 仅当 usedImports 为空时触发 resolver 始终对未命中标识符尝试 resolver
DTS 生成 initialize() 和 buildEnd 可能重复写入 dtsGeneratedInInit 标志避免冗余写入
解析引擎 多种格式分别处理 resolveImportsConfig 统一处理预设/Record/Inline 等
通配符导出解析 回退到运行时入口（可能不完整） 优先从 .d.ts 解析（最准确），回退到运行时入口
类型体系 ImportMapping + ResolvedImport 两套类型 统一为 ImportInline 单一类型
旧版兼容 compat.ts 处理旧格式转换 移除兼容层，仅支持新格式

五、配置选项完整对照

选项 1.0.0 1.1.0 说明
imports ✅ Record ✅ 增强 新增预设字符串、别名、类型导入等格式
dirs ✅ string\[\] ✅ 增强 支持 DirConfigObject 和 glob 模式
dts ✅ ✅ 增强 新增 DtsConfig 对象（filepath + mode）
vueTemplate ✅ ✅ 不变 保留，同时新增 vueDirectives
ignore ✅ ✅ 不变 ---
include --- ✅ 新增 文件包含过滤（替代 fileFilter）
exclude --- ✅ 新增 文件排除过滤
dtsMode --- ✅ 新增 'append' 或 'overwrite'
dtsPreserveExts --- ✅ 新增 DTS 中保留文件扩展名
eslintrc --- ✅ 新增 ESLint globals 配置生成
biomelintrc --- ✅ 新增 Biome globals 配置生成
resolvers --- ✅ 新增 自定义解析器
packagePresets --- ✅ 新增 包预设
cache --- ✅ 新增 缓存配置（默认 true）
ignoreDts --- ✅ 新增 DTS 忽略列表
viteOptimizeDeps --- ✅ 新增 Vite 预优化集成（默认 false）
commentsDisable --- ✅ 新增 注释禁用标记列表
vueDirectives --- ✅ 新增 Vue 指令自动导入配置
dirsScanOptions --- ✅ 新增 目录扫描选项
defaultExportByFilename --- ✅ 新增 默认导出按文件名
injectAtPosition ✅ ✅ 不变 ---
fileFilter ✅ ❌ 移除 使用 include/exclude 替代

六、子路径导出变更

6.1 移除的导出

  • 类型：ImportMapping、ResolvedImport
  • 函数：migrateLegacyOptions、resolvedImportToInline、inlineToResolvedImport、importMappingToInlines

6.2 新增的导出

  • 类型：ImportInline、PresetDefinition、DirConfig、DirConfigObject、DirsScanOptions、DtsConfig、DtsConfigObject、InlineImportConfig、EslintrcConfig、BiomelintrcConfig、AutoImportCache、CacheConfig、VueDirectivesConfig、ImportMeta
  • 函数：resolveImportsConfig、buildNameLookup、findPreset、expandPreset、resolvePackagePreset、generateEslintrc、generateBiomelintrc

七、实战场景

7.1 纯 Vite 项目（推荐配置）

typescript 复制代码 
import { defineConfig } from 'vite'
import { autoImport } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		autoImport({
			imports: ['vue', 'vue-router', 'pinia'],
			dts: 'src/auto-imports.d.ts',
			vueTemplate: true,
			viteOptimizeDeps: true, // 纯 Vite 项目可安全开启
			eslintrc: { enabled: true }
		})
	]
})

7.2 uni-app 项目

typescript 复制代码 
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { autoImport } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		uni(),
		autoImport({
			imports: ['vue'],
			dts: true,
			vueTemplate: true
			// ⚠️ uni-app 中不要开启 viteOptimizeDeps（vue 已被框架 external 化）
		})
	]
})

7.3 目录扫描 + 自定义 composables

typescript 复制代码 
autoImport({
	imports: ['vue'],
	dirs: ['./src/composables/**', './src/utils'],
	dts: { filepath: 'src/auto-imports.d.ts', mode: 'append' },
	dirsScanOptions: {
		fileFilter: file => !file.includes('.test.')
	}
})

7.4 注释禁用

typescript 复制代码 
// 整个文件禁用自动导入
// @unimport-disable

// 仅某一行禁用
// const x = someGlobal() // @unimport-disable

八、升级指南

8.1 从 1.0.0 升级

bash 复制代码 
pnpm update @meng-xi/vite-plugin@^1.1.0

无需修改代码的情况（大多数用户）：

  • 使用 imports: { vue: ['ref', 'reactive'] } Record 格式 → 仍支持
  • 使用 imports: { vue: ['*'] } 通配符 → 仍支持，推荐改为 'vue'
  • 使用 dirs: ['./composables'] → 仍支持

需要修改代码的情况：

场景 修改方式
使用了 ImportMapping 类型 改为 InlineImportConfig 或预设字符串
使用了 ResolvedImport 类型 改为 ImportInline
使用了 fileFilter 选项 改为 include / exclude
直接引用了 helpers/compat 移除引用，旧格式不再支持

8.2 推荐优化

升级后推荐逐步迁移到新特性：

typescript 复制代码 
// 旧：手动列举
autoImport({ imports: { vue: ['ref', 'reactive', 'computed', 'watch'] } })

// 新：使用预设（覆盖更全，后续版本自动增加新 API）
autoImport({ imports: ['vue'] })

8.3 升级后验证

bash 复制代码 
# 开发模式验证
vite dev

# 检查 DTS 生成
cat src/auto-imports.d.ts

# 如启用了 ESLint 配置生成
cat .eslintrc-auto-import.json

写在最后

v1.1.0 是 1.x 系列的第一个功能增强版本，聚焦于 autoImport 插件的全面升级。

重构后的 autoImport 插件在功能完整度、配置便利性和构建性能上都有显著提升：

  • 预设系统让常用库配置从手动列举变为一行搞定，且覆盖更全
  • 多种导入形式满足 alias、type、namespace 等实际需求
  • Lint 配置生成 解决了长期困扰的 no-undef 报错问题
  • 缓存与 HMR让开发体验更流畅

后续 1.x 版本将聚焦于：更多内置预设（vueuse、axios 等）、Vue 3.5+ 新 API 支持、性能持续优化。如果你有任何建议或问题，欢迎在 GitHub Issues 反馈。

相关推荐
RobinDevNotes7 分钟前
从 Electron 到 GPUI，9 个跨平台桌面方案该怎么选
前端·javascript·rust·electron·openresty·前端开发工具
jay神1 小时前
基于 YOLOv8 的轴承缺陷检测（Web 版）
前端·人工智能·yolo
jay神1 小时前
基于 YOLOv8 的森林火灾检测系统（Web 版）
前端·yolo
code2cat1 小时前
HTML基础篇之第一张网页：从index.html到浏览器里的任务清单
前端·html
miss2 小时前
AI 改完不敢上线？OpenSpec 规约驱动开发实战
前端·代码规范·前端工程化
AiMan3 小时前
腾讯ima还是不可以导出左侧所有对话，只能单条导出，方法不对吗
前端
去伪存真3 小时前
并发量一高就装死？Agent 全链路“防猝死”手册
前端·agent
Moment3 小时前
AI 编程时代，聊聊我的 Mac mini 双屏桌面
前端·后端
AiMan3 小时前
先确认能不能一次把Microsofat Copilot所有内容打包一个文件导出
前端
总要学点什么3 小时前
第97篇：三维数据加载-城市建筑白模自定义着色器——让一条光带沿高度扫上去，快慢却由帧率说了算
前端·gis·webgl·cesium·着色器·空间分析·白模
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03历年考研数学一、数学二、数学三真题试卷及答案PDF04几个好用的ip纯净度检测网站05GitHub 镜像站点06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新07昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战08苹果iPA游戏软件资源下载网站09蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接10Dify：一站式AI应用开发平台全解析与Windows部署指南