VueUse需按需引入核心包@vueuse/core，配合unplugin-auto-import实现自动导入与TS类型支持，禁用全局注册，确保tree-shaking有效且类型完备。

VueUse 是 Vue 3 生态中不可或缺的组合式工具库，它把大量常见逻辑（如响应式 DOM 操作、异步状态管理、搜索、可见性判断等）封装成开箱即用的 useXxx 函数。初始化项目时集成 VueUse，关键不是“装上就行”，而是要按需引入、避免冗余、适配 TypeScript 和构建工具链。

安装核心包与按需集成

VueUse 分为两个主要包：@vueuse/core（基础工具）和 @vueuse/integrations（第三方库封装，如 axios、fuse.js）。不要一次性全量安装：

• 先装核心： npm install @vueuse/core
• 只在需要时再装集成包，例如用模糊搜索才加：npm install @vueuse/integrations fuse.js@^7（注意 fuse.js 是 peer dependency，必须显式安装）
• 若用 useAxios，还需额外安装：npm install axios@^1

TS 类型支持与自动导入（推荐 Volar + unplugin-auto-import）

VueUse 的类型定义已内建，但为了让 useXxx 函数在 .vue 文件中无需手动 import 就能获得类型提示和自动补全，建议搭配自动化方案：

• 安装插件：npm install -D unplugin-auto-import
• 在 vite.config.ts 中配置（Vite 项目）：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      imports: ['vue', '@vueuse/core'],
      dts: './src/auto-imports.d.ts', // 生成类型声明文件
    }),
  ],
})

配置后重启 VS Code（确保已启用 Volar），useRef、useAsyncState、useElementVisibility 等函数将自动可用且带完整类型。

vue-composition-api-best-practices

Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。

下载

立即学习“前端免费学习笔记（深入）”；

按需使用，不默认全局注册

VueUse 的设计哲学是「组合式」而非「插件式」，不推荐在 main.ts 中全局挂载或注册——它没有 app.use() 接口。所有函数都应以解构方式按需调用：

import { useAsyncState, useDebounceFn } from '@vueuse/core'

export default defineComponent({
  setup() {
    const { state, isLoading } = useAsyncState(fetchUser(), null)
    const debouncedSearch = useDebounceFn(search, 300)
    return { state, isLoading, debouncedSearch }
  }
})

这样既保证 tree-shaking 有效，又让逻辑职责清晰可测。

验证集成是否生效

快速检查是否配置成功，可在任意 .vue 文件的 <script setup> 中尝试：

• 输入 use，看是否出现 useAsyncState、useStorage 等建议项
• 写一行 const visible = useElementVisibility(document.body)，确认无 TS 报错且 visible.value 类型为 boolean
• 运行项目，打开控制台，确认无 Cannot find module 或 undefined is not a function 错误