VueUse 是 Vue Composition API 的工具函数集合，提供 200+ 个响应式工具函数。配合 unplugin-auto-import 实现零导入使用，大幅减少样板代码。本文讲解 VueUse 集成、自动导入配置及类型声明的协作机制。
pnpm add -D unplugin-auto-import
pnpm add @vueuse/core// vite.config.ts
import AutoImports from 'unplugin-auto-import/vite'
export default defineConfig({
plugins: [
vue(),
AutoImports({
imports: [
'vue',
'vue-router',
'@vueuse/core',
],
dts: 'auto-imports.d.ts',
eslintrc: {
enabled: true,
filepath: '.eslintrc-auto-import.json',
},
}),
],
})<script setup lang="ts">
// 无需 import，直接使用
const count = ref(0)
const doubled = computed(() => count.value * 2)
const { x, y } = useMouse()
const isDark = useDark()
</script>| 函数 | 用途 |
|---|---|
useStorage | 响应式 localStorage/sessionStorage |
useDark | 暗色模式切换 |
useToggle | 布尔值切换 |
useCounter | 计数器 |
| 函数 | 用途 |
|---|---|
useMouse | 鼠标位置追踪 |
useWindowSize | 窗口尺寸 |
useIntersectionObserver | 元素可见性 |
useClipboard | 剪贴板操作 |
| 函数 | 用途 |
|---|---|
useFetch | 响应式 fetch |
useWebSocket | WebSocket 连接 |
useOnline | 网络在线状态 |
<script setup lang="ts">
// 响应式本地存储
const settings = useStorage('app-settings', {
theme: 'light',
fontSize: 14,
})
// 元素可见性检测
const target = ref<HTMLElement>()
const { stop } = useIntersectionObserver(target, ([{ isIntersecting }]) => {
if (isIntersecting) {
console.log('元素进入视口')
stop()
}
})
</script>
<template>
<div ref="target">监听此元素</div>
</template>插件自动生成的类型声明文件，让 TypeScript 识别全局可用的 API：
// auto-imports.d.ts（自动生成，勿手动修改）
declare const ref: typeof import('vue')['ref']
declare const computed: typeof import('vue')['computed']
declare const useMouse: typeof import('@vueuse/core')['useMouse']{
"include": [
"auto-imports.d.ts",
"components.d.ts"
]
}自动导入的变量会被 ESLint 的 no-undef 规则报错。解决方案：
.eslintrc-auto-import.json（插件自动生成）：
{
"globals": {
"ref": true,
"computed": true,
"useMouse": true
}
}在 ESLint 配置中引入：
// eslint.config.js
import autoImportGlobals from './.eslintrc-auto-import.json'
export default [
{
languageOptions: {
globals: autoImportGlobals.globals,
},
},
]Q: 自动导入会影响 Tree-shaking 吗？
不会。unplugin-auto-import 在编译时将未使用的导入移除，最终产物只包含实际使用的函数。
Q: VueUse 和 lodash 可以共存吗？
可以，但建议优先使用 VueUse 的响应式版本（如 useDebounceFn 替代 lodash.debounce），因为 VueUse 函数天然支持响应式和自动清理。