写Vue3的自定义Hooks其实是在写一种“把状态逻辑从组件里抽出来”的思维习惯。很多人学了组合式API知道ref、computed、watch怎么用但真到项目里一个组件动辄几百行各种业务状态揉在一起又回到Option API那套“data里塞一堆字段methods里写一堆函数”的老路。自定义Hooks就是用来打破这个局面的——它不是一个新API也不是框架的隐藏功能而是基于Vue3组合式API天然长出来的一种代码组织模式。这篇文章我想从实际开发的角度把自定义Hooks从定位、基础API到复杂场景的组织方式再到排查问题的心得完整地梳理一遍希望能给正在学Vue3或者已经在项目里折腾组合式函数的同学一些参考。这篇文章适合谁正在学Vue3、准备面试、或者已经在后台管理系统、可视化大屏这类中后台项目里用Vue3写业务代码的开发者。文章不会只讲概念会给出大量可以直接抄的代码和设计思路也会讲一些文档里不会写的坑。1. 自定义Hooks到底是什么它解决了什么问题1.1 从一次真实的重构说起先聊一个我印象很深的场景。之前做一个后台管理系统有一个订单列表页一开始用Vue2的Option API写data里放了loading、tableData、pageNum、pageSize、total、searchForm这些字段methods里写loadData、handleSearch、handleReset、handlePageChange、handleSizeChange还要配合watch去监听分页数据变化。写完之后功能是正常的但有两个问题特别明显第一这个组件有将近400行想找一个字段的赋值逻辑要来回滚第二同样的“列表分页搜索”这套逻辑在用户管理、商品管理、角色管理这几个页面里几乎原样复制了一遍只是接口地址和字段名不同。后来用Vue3重写我把这套逻辑抽成了一个useTable函数。每个列表页的代码从400行降到了100行左右剩下的全是页面特有的列配置和操作函数。更重要的是后面再遇到新页面直接const { tableData, loading, page, handleSearch } useTable({ fetchApi: fetchUserList })几行代码就搞定了。这是自定义Hooks最直观的价值——它是可复用的状态逻辑单元比mixin更干净比组件更轻量。1.2 为什么说Hooks是“组合式API的建筑模块”Vue3引入了组合式API但组合式API本身只给了你一块空地怎么盖房子是你自己的事。自定义Hooks本质上就是“把一组相关的状态和操作状态的方法封装进一个独立函数里”。它和普通函数的区别在于函数内部可以使用ref、reactive、computed、watch这些响应式API并且返回给调用者的状态天然是响应式的。一个典型的自定义Hooks长这样// useCounter.ts import { ref, computed } from vue export function useCounter(initialValue 0) { const count ref(initialValue) const double computed(() count.value * 2) const increment () { count.value } const decrement () { count.value-- } const reset () { count.value initialValue } return { count, double, increment, decrement, reset } }看起来很简单对不对但就是这个简单的模式解决了mixin时代三个老大难问题数据来源不透明。mixin里的数据你只能打开mixin文件才能看到组件里用的时候根本分不清某个字段到底来自哪个mixin。自定义Hooks则不同你通过解构返回值明确知道数据是从哪里来的。命名冲突无法根治。两个mixin都定义了data字段合并时后者覆盖前者很难排查。自定义Hooks是函数作用域变量名在函数内部就算两个Hooks都返回data你在组件里解构时重命名一下就行const { data: userData } useUser()。逻辑复用不灵活。mixin是静态合并的没法在运行时按条件加入。自定义Hooks是函数调用你可以随时决定“这个组件要不要用这个逻辑”甚至可以在函数内部通过参数动态控制行为。1.3 哪些场景最适合用自定义Hooks不是所有逻辑都适合抽成Hooks。我个人的经验是以下三类场景收益最大第一类是有明确生命周期参与的异步逻辑比如请求数据、WebSocket连接、定时器管理。这类逻辑最大的痛点是“清理”组件卸载时忘了解绑事件、清定时器就会留下内存泄漏或重复触发。Hooks可以把onMounted、onUnmounted都封装起来调用方只需要关心业务。第二类是跨组件共享的UI状态逻辑。比如主题切换、语言切换、折叠侧边栏、全屏状态。这些状态往往在多个组件里用到但又不够“重”到需要引入Pinia。用Hooks加模块级作用域变量就可以实现轻量共享。第三类是复杂表单逻辑。后台管理系统里表单特别多而且都是“初始化数据、字段校验、提交、回填”这套流程。抽成useForm这样的Hooks之后页面代码可以清爽很多。反过来如果一个逻辑只在单个组件里用到而且就几行代码那先不要急着抽象。用了自定义Hooks不代表代码就变好了滥用一样会产生过度设计的问题。2. 地基组合式API的核心工具怎么用扎实2.1 ref、reactive和toRefs状态定义的正确姿势自定义Hooks里最核心的工作就是创建和返回响应式状态。很多新手纠结到底用ref还是reactive我的经验是分情况处理。ref适合表示单个值类型状态比如数字、布尔值、字符串它的优势是访问统一.value传参和返回都比较方便。reactive适合一组强关联的字段比如一个表单对象{ name: , age: 0, email: }用reactive定义后不用写一堆.value。但reactive有个坑当你把它return出去在组件里解构时会丢失响应性。比如function useForm() { const form reactive({ name: , age: 0 }) return { form } } // 组件里 const { form } useForm() form.name 张三 // 没问题响应式还在但如果直接解构成多个字段const { name, age } useForm() name // 此刻已经是一个普通字符串了改它不会触发更新所以返回reactive对象时要么整个对象返回要么用toRefs把它转成一个个ref再返回。在我自己的项目里默认习惯是Hooks内部用ref定义状态返回值统一用ref。这能最大程度避免调用方踩“解构丢失响应性”的坑。2.2 computed和watch派生状态和副作用处理自定义Hooks里第二类常用工具是computed和watch。computed适合做派生状态比如“分页后的数据总数”“筛选后的列表”“购物车总价”。注意computed一定是基于已有状态的纯函数不要在computed里发请求、改状态。watch适合响应式副作用比如监听某个值变化后做异步操作。写Hooks时如果一个watch不在组件里显式声明而是藏在Hooks内部要注意两点第一watch默认是懒执行的如果你希望在初始化时就执行一次需要显式加immediate: true。第二watch的清理回调很重要比如你监听关键词变化发搜索请求可能在旧请求还没返回时新请求就发出去了需要在清理回调里把旧的请求取消掉否则会出现竞态问题。watch(searchKeyword, async (newVal) { const result await searchApi(newVal) // 如果此时searchKeyword已经变了result其实是过期数据 data.value result })上面这种写法就是典型的竞态问题。解决方案是在watch回调里用一个布尔标记或者用AbortController取消旧请求更推荐的做法是让请求本身支持取消。2.3 生命周期钩子Hooks里的“隐形逻辑”自定义Hooks最大的威力之一就是把生命周期逻辑也封装进去。比如一个useMousePosition的Hooksimport { ref, onMounted, onUnmounted } from vue export function useMousePosition() { const x ref(0) const y ref(0) const update (e: MouseEvent) { x.value e.clientX y.value e.clientY } onMounted(() window.addEventListener(mousemove, update)) onUnmounted(() window.removeEventListener(mousemove, update)) return { x, y } }在组件里调用useMousePosition()组件挂载时自动监听卸载时自动移除完全不用组件关心清理逻辑。这里有一个很容易被忽略的细节onMounted、onUnmounted这些生命周期函数必须在setup执行期间同步调用。所以自定义Hooks里调用生命周期函数必须在setup函数中同步执行Hooks的调用不可以在异步回调里调用onMounted否则Vue会警告“onMounted is called when there is no active component instance”。这也是为什么Hooks的命名习惯通常以use开头提醒开发者只能在setup环境里使用它们。3. 从零实践三个高频业务场景的Hooks封装3.1 5分钟实现一个useCountDown倒计时Hooks先从一个最简单但最常见的场景开始倒计时。很多场景要用到比如发送验证码后的60秒倒计时、活动开奖倒计时。直接写的话每个组件都要处理定时器的创建和清理很容易漏。这个Hooks的核心参数和返回值先定下来// useCountDown.ts import { ref, onUnmounted } from vue export function useCountDown(initialSeconds: number) { const seconds ref(initialSeconds) let timer: ReturnTypetypeof setInterval | null null const start () { if (timer) return timer setInterval(() { if (seconds.value 0) { stop() return } seconds.value-- }, 1000) } const stop () { if (timer) { clearInterval(timer) timer null } } const reset () { stop() seconds.value initialSeconds } onUnmounted(stop) return { seconds, start, stop, reset } }调用方式也很直接const { seconds, start, reset } useCountDown(60) const handleSendCode () { // 校验手机号逻辑略 start() // 启动倒计时 // 调用发送验证码接口 }这里有几个细节值得注意。timer用let定义在Hooks内部这样多个组件实例各自调用时会创建各自的闭包作用域互不干扰。setInterval的返回类型在浏览器环境是number在Node环境是Timeout所以用了ReturnTypetypeof setInterval来规避类型问题。stop函数里把timer置为null是为了防止重复start时创建多个定时器。最后在onUnmounted里调用stop保证组件销毁时不会留下定时器。3.2 中后台必备useTable封装表格分页搜索逻辑接下来是后台管理系统里含金量最高的一个HooksuseTable。这套逻辑几乎出现在每一个列表页面中值得花点心思设计。目标很明确封装“加载数据、分页变化、搜索重置”这一整套流程让业务组件只关注“接口和数据列”。// useTable.ts import { ref, reactive, onMounted } from vue interface PageInfo { pageNum: number pageSize: number total: number } interface UseTableOptionsT { fetchApi: (params: any) Promise{ list: T[]; total: number } defaultParams?: Recordstring, any immediate?: boolean } export function useTableT(options: UseTableOptionsT) { const { fetchApi, defaultParams {}, immediate true } options const tableData refT[]([]) const loading ref(false) const pageInfo reactivePageInfo({ pageNum: 1, pageSize: 10, total: 0 }) const searchForm reactive({ ...defaultParams }) const loadData async () { loading.value true try { const params { pageNum: pageInfo.pageNum, pageSize: pageInfo.pageSize, ...searchForm } const res await fetchApi(params) tableData.value res.list pageInfo.total res.total } finally { loading.value false } } const handleSearch () { pageInfo.pageNum 1 // 搜索时回到第一页 loadData() } const handleReset () { Object.keys(searchForm).forEach(key { searchForm[key] }) handleSearch() } const handlePageChange (page: number) { pageInfo.pageNum page loadData() } const handleSizeChange (size: number) { pageInfo.pageSize size pageInfo.pageNum 1 loadData() } onMounted(() { if (immediate) loadData() }) return { tableData, loading, pageInfo, searchForm, loadData, handleSearch, handleReset, handlePageChange, handleSizeChange } }这个设计里有几个关键决策。一个是searchForm用reactive而不是ref因为表单字段天然就是一组键值对在模板里用v-modelsearchForm.name直接绑定很方便不需要写.value。另一个是loadData里组装请求参数时把searchForm展开放在后面这样如果接口有额外的必传参数比如projectId业务方可以把它的值放到searchForm里如果不想污染搜索表单也可以在默认参数里处理或者干脆把额外的固定参数通过fetchApi闭包传出去。再一个是handleReset中重置时要把pageNum设回1否则你从第5页点重置列表数据会从第5页开始加载体验很怪。这类细节是Hooks设计时最容易被忽略的。组件里的使用效果const { tableData, loading, pageInfo, searchForm, handleSearch, handleReset, handlePageChange, handleSizeChange } useTable({ fetchApi: fetchOrderList, defaultParams: { status: } })模板里的el-table、el-pagination只需要绑定这些返回的状态和函数就行了。如果后续某个页面需要在数据加载成功后做一些额外处理可以把loadData暴露出去在页面里await loadData()之后继续执行逻辑甚至还可以给useTable增加一个afterFetch回调参数。这些都是可以按需扩展的点。3.3 手写一个简化版useRequest防抖、Loading和错误处理再往前一步很多中后台项目会接入useRequest这类请求Hooks库但依赖一个第三方库有时候觉得重。实际上用Vue3的组合式API手写一个够用的useRequest并不难而且能完全按自己项目的需求定制。我先讲讲核心思路把“发请求”这个行为封装成run函数loading、data、error都是响应式状态。这里直接上实现// useRequest.ts import { ref } from vue export function useRequestT, P extends any[](fetcher: (...args: P) PromiseT) { const data refT | null(null) const loading ref(false) const error refError | null(null) const run async (...args: P) { loading.value true error.value null try { data.value await fetcher(...args) return data.value } catch (e) { error.value e as Error throw e } finally { loading.value false } } return { data, loading, error, run } }这个版本解决的问题是“每次都要手动写loading开关”的痛。但实际项目里往往还需要防抖、竞态处理、轮询这些能力。我们给run加一个防抖控制export function useRequestT, P extends any[]( fetcher: (...args: P) PromiseT, options: { debounceWait?: number } {} ) { const { debounceWait 0 } options // ...省略前文状态 let timer: ReturnTypetypeof setTimeout | null null const run (...args: P) { if (debounceWait) { if (timer) clearTimeout(timer) return new PromiseT((resolve, reject) { timer setTimeout(async () { try { const res await fetcher(...args) data.value res resolve(res) } catch (e) { error.value e as Error reject(e) } finally { loading.value false } }, debounceWait) }) } // 非防抖逻辑略 } // ... }防抖版的run返回的是一个Promise这样调用方可以继续使用await这一点在“点击搜索后还要跳转页面”这种场景里很有用。竞态处理我上面提到过这里再给一个更简单的方案在run里维护一个自增的requestId每次请求发起前记录当前ID响应返回后对比ID如果不一致就丢弃结果。这个方法比AbortController兼容性更好代码也容易理解。let currentId 0 const run async (...args: P) { const requestId currentId loading.value true try { const res await fetcher(...args) if (requestId ! currentId) return undefined // 过期响应直接丢弃 data.value res return res } finally { if (requestId currentId) loading.value false } }4. 进阶复杂业务中Hooks的设计模式4.1 Hooks组合Hooks把一个复杂逻辑拆成可复用的小单元单层Hooks解决单类问题当业务变复杂时可以Hooks之间互相组合。这就像搭积木积木本身可以先做小然后用小积木拼大积木。举个例子做一个可视化大屏项目需要实时轮询接口数据。我可以先写一个useInterval的通用Hooks负责定时器调度import { onUnmounted } from vue export function useInterval(fn: () void, delay: number | null) { let timer: ReturnTypetypeof setInterval | null null const start () { if (delay null || timer) return timer setInterval(fn, delay) } const stop () { if (timer) { clearInterval(timer) timer null } } onUnmounted(stop) return { start, stop } }然后在大屏的useDashboardData里组合它import { ref } from vue import { useInterval } from ./useInterval export function useDashboardData(fetchApi: () Promiseany, intervalMs 5000) { const data refany(null) const refresh async () { data.value await fetchApi() } const { start, stop } useInterval(refresh, intervalMs) const startPolling () { refresh() start() } return { data, startPolling, stop, refresh } }这样设计的好处是useInterval本身是通用的跟“大屏”“轮询数据”没有耦合可以被任意需要定时器的场景复用。组合模式让每个单元的职责单一测试和排查问题都容易很多。4.2 共享状态型Hooks用模块级变量实现轻量级全局状态有一种情况很常见某个状态需要在一部分组件间共享但又没到全局状态管理的程度。这时候可以在Hooks文件里用模块级作用域的变量来实现“轻量级Pinia”。// useTheme.ts import { ref } from vue const isDark ref(false) // 模块级变量整个应用共享同一个状态 export function useTheme() { const toggleDark () { isDark.value !isDark.value } const setDark (val: boolean) { isDark.value val } return { isDark, toggleDark, setDark } }这个模式有几个注意点。第一模块级变量在应用生命周期内是持久的如果你需要每个组件实例独立的副本那还是应该在函数内部创建变量。第二模块级响应式状态相当于隐式的全局单例使用得当是利器使用过度会让数据流变得混乱。我的经验是推荐用于“主题、布局、用户偏好”这类全局UI状态不推荐用于业务数据因为业务数据变更复杂需要配合服务端状态管理。4.3 Hooks与TypeScript的配合泛型带来的类型解放现在的Vue3项目基本都是TS环境自定义Hooks和泛型是天然搭档。还拿useTable举例我在封装时就让它继承传入数据类型// 调用时 interface User { id: number name: string email: string } const { tableData } useTableUser({ fetchApi: fetchUserList }) tableData.value // 自动提示 User[]泛型的意义不仅仅是类型检查更重要的是开发体验。写tableData.value时编辑器能自动补全id、name、email这几个字段少了很多手工查接口文档的时间。如果你的团队正在用若依Vue3或者自己搭的后台模板建议从一开始就要求封装的Hooks带泛型否则后期改类型会非常痛苦。有一个TS相关的坑容易踩reactive对象的类型推导。比如const pageInfo reactive({ pageNum: 1, pageSize: 10 }) // pageInfo的类型是 { pageNum: number; pageSize: number } // 后面想给pageInfo加一个total字段会报错 pageInfo.total 0 // 类型错误在对象字面量推倒后不允许新增属性正确做法是显式声明接口变量或者用ref定义整个对象。这一点在写Hooks时特别常见新同学容易卡住。5. 实战中的问题排查与避坑记录5.1 常见报错onMounted被调用时没有活动组件实例这是新手最容易踩的问题我在网上搜热词时也看到很多人问。错误现象是在控制台看到警告onMounted is called when there is no active component instance。原因通常是你在某些生命周期钩子之外或者在异步操作里调用了onMounted。比如const useFetchData async () { const res await api.getData() onMounted(() { // 错误请求完成后同步环境早已结束 }) return res }onMounted这些生命周期函数只能在setup函数执行期间的同步代码里注册因为它需要拿到当前正在执行setup的组件实例上下文。一旦代码进入异步回调这个上下文就没了。解决方案很简单把生命周期相关调用放在同步阶段等待数据之类的逻辑放在生命周期内部const useFetchData () { const data ref(null) onMounted(async () { data.value await api.getData() }) return data }5.2 响应式丢失问题解构与嵌套的陷阱前面讲reactive时说过解构丢失响应式的问题实际上自定义Hooks里还有一个容易踩的变体从Hooks返回的reactive对象在组件模板里消费没问题但如果把它作为值传入普通函数再在函数里修改属性响应性是保留的因为对象的引用没变可如果你把它解构成了多个变量普通函数里改的是基本类型值就丢了响应式。此外在Pinia或组件里把一个Hooks返回的ref对象直接赋值给响应式对象的属性也可能出现意想不到的问题比如const { data } useData() const store reactive({ list: data }) // 这里list其实是ref对象访问时需要store.list.value容易忘记我建议的习惯是所有Hooks返回值统一采用“ref 原始类型”的组合返回复杂对象时用reactive就整包返回不让调用方自己拆零。5.3 循环引用与接口重复请求使用useTable或useRequest时有些人会遇到接口重复请求的问题。排查思路一般是首先看是否在onMounted里调了一次又在模板里通过计算属性或watch隐式触发了一次。比如const { run } useRequest(fetchData) onMounted(run) // 模板里 div v-ifloading加载中/div没有明显问题但如果模板里某处直接调用了函数而不是引用变量button clickgetList()刷新/button点击后没问题但响应式依赖追踪会把“调用函数”和“渲染”挂钩如果有代码在函数内修改了被模板依赖的状态就可能触发额外的渲染链路。解决办法是保证加载数据等操作都在事件处理函数或生命周期中执行模板事件里尽量调用Hooks暴露的方法而不是裸函数。5.4 从Vue2迁移到Vue3的Hooks改造建议如果你正在把Vue2项目迁移到Vue3我建议不要直接把Option API搬成组合式API丢到一起。借助自定义Hooks迁移可以大幅降低代码维护成本这样操作第一先按业务模块拆分。浏览组件的data和methods把互相强相关的字段和函数放一起。比如“搜索表单相关”放一组“弹窗相关”放一组“表格数据相关”放一组。第二把每一组抽成独立Hooks。不必一步到位先把data里的字段变成refmethods里的函数提到Hooks内部。运行测试保证结果和原来一致。第三合并重复逻辑。多个页面有相似逻辑时用参数和泛型把Hooks合并成通用版本再在每个页面替换。这一步做完你会发现组件代码变得非常友好新需求来的时候可以直接在Hooks层面扩展不用再去几百行的组件里找代码。6. 常见问题速查表这里整理一份我在工作中经常用到的排查表方便对照。问题现象原因分析解决方案Hooks中调用onMounted报错生命周期函数在异步回调中执行确保在setup同步期间调用解构reactive对象后修改不更新解构出的值是普通类型丢失代理返回时用toRefs或整体返回对象多个组件调用同一个Hooks状态互相污染变量定义在模块级作用域把状态定义移到Hooks函数内部定时器在页面切换后仍在运行忘记在onUnmounted中清理Hooks内部封装生命周期清理逻辑表单重置后分页数据没有回到第一页重置逻辑没有重置pageNum搜索和重置时统一设置pageNum为1接口请求竞态导致数据显示旧内容多个请求并发响应到达顺序不一致使用requestId或AbortController丢弃过期响应useTable重复请求数据onMounted和模板副作用同时触发检查调用来源确保加载只触发一次组件间无法共享同一个Hooks状态每次调用Hooks都创建新的闭包状态用模块级变量或Pinia管理全局状态7. 自定义Hooks的扩展思考文章写到这核心内容基本都覆盖了。最后再分享两个我实际项目中的体会。第一个是Hooks不是越通用越好。之前我们团队封装过一个特别复杂的useForm支持校验、动态表单项、联动、提交回填几十个配置项结果新同学完全不敢碰改需求成本很高。后来拆成useFormValues、useFormValidation、useFormSubmit三个小Hooks按需组合反而灵活了。第二个建议是给Hooks写一点文档和示例。代码写得再优雅同事不一定会用。我现在习惯在每个Hooks文件顶部用注释写清参数、返回值、使用场景和一个最小示例。半年后再打开项目你会发现这些注释帮了大忙。Vue3自定义Hooks的威力不在API本身而在于“组合”的思维方式。它可以让你的业务逻辑从组件里解放出来可以被单元测试覆盖可以被任意组件复用同时大幅缩小组件代码体积。如果你正在一个中后台项目里用Vue3找个周末把手上的列表页或者表单页试着抽一个Hooks出来感受一下前后对比我相信你会喜欢上这种写代码的方式。