Vue 3 自定义指令 + 完整生命周期详解（2025–2026 实用版）
Vue 3 的自定义指令和组件生命周期是中高级开发中非常高频的内容，尤其在以下场景中几乎必考/必用：
- 复杂表单（自动聚焦、输入防抖、权限显隐）
- 拖拽、长按、水印、懒加载图片
- 第三方库集成（图表 resize、虚拟滚动优化）
- 调试/埋点/权限控制指令
下面把自定义指令和组件生命周期放在一起讲解，因为它们在实际项目中经常结合使用。
一、Vue 3 组件生命周期（Composition API 版为主）
Vue 3 Composition API 使用onXXX钩子函数，Options API 则使用beforeCreate等选项。
| 阶段 | Options API | Composition API | 执行时机（最常用场景） | 是否异步 |
|---|---|---|---|---|
| beforeCreate | beforeCreate | —（不推荐） | 实例初始化之前，几乎不用 | 同步 |
| created | created | —（不推荐） | 数据响应式处理完成，可访问 data / props | 同步 |
| beforeMount | beforeMount | onBeforeMount | 模板编译完成，即将挂载到 DOM 前 | 同步 |
| mounted | mounted | onMounted | 组件挂载完成，DOM 已渲染，可操作真实 DOM | 同步 |
| beforeUpdate | beforeUpdate | onBeforeUpdate | 数据变化 → 重新渲染前（可获取旧 DOM 状态） | 同步 |
| updated | updated | onUpdated | DOM 更新完成（注意：不要在这里修改响应式数据） | 同步 |
| beforeUnmount | beforeUnmount | onBeforeUnmount | 组件即将卸载（清理定时器、事件监听、订阅等） | 同步 |
| unmounted | unmounted | onUnmounted | 组件完全卸载，DOM 已移除 | 同步 |
| activated | activated | onActivated | keep-alive 组件被激活时 | 同步 |
| deactivated | deactivated | onDeactivated | keep-alive 组件失活时 | 同步 |
| errorCaptured | errorCaptured | onErrorCaptured | 捕获子组件错误（可返回 false 阻止抛出） | 同步 |
| renderTracked | — | onRenderTracked | 响应式依赖被追踪（调试用） | — |
| renderTriggered | — | onRenderTriggered | 响应式依赖被触发重新渲染（调试用） | — |
| serverPrefetch | — | onServerPrefetch | SSR 预取数据（Nuxt / Vite SSR 常用） | — |
最常用的 5 个钩子（日常开发占比 90%+）：
onMounted→ 获取 DOM、发起首次请求、初始化第三方库onBeforeUnmount/onUnmounted→ 清理定时器、事件监听、WebSocket 断开onUpdated→ DOM 更新后做一些微调（慎用，避免死循环）onActivated/onDeactivated→ keep-alive 场景（列表缓存、音频播放暂停）onErrorCaptured→ 组件级错误边界
代码示例（组合式 API 完整写法）
<script setup> import { ref, onMounted, onBeforeUnmount, onActivated, onDeactivated } from 'vue' const count = ref(0) let timer = null onMounted(() => { console.log('组件已挂载，可以操作 DOM') timer = setInterval(() => count.value++, 1000) }) onBeforeUnmount(() => { console.log('组件即将卸载，清理资源') clearInterval(timer) }) onActivated(() => { console.log('keep-alive 组件被激活') // 可重新启动轮询、视频播放等 }) onDeactivated(() => { console.log('keep-alive 组件失活') // 暂停轮询、视频等 }) </script>二、Vue 3 自定义指令（v-xxx）
Vue 3 自定义指令的钩子函数比 Vue 2 精简了很多，统一成了6 个生命周期：
| 钩子名称 | Options API 写法 | Composition API 写法（directive） | 执行时机 | 是否传入 el |
|---|---|---|---|---|
| created | created | created | 指令绑定到元素时，在 beforeMount 之前 | 是 |
| beforeMount | beforeMount | beforeMount | 元素挂载前 | 是 |
| mounted | mounted | mounted | 元素挂载完成后（最常用） | 是 |
| beforeUpdate | beforeUpdate | beforeUpdate | 包含组件的 VNode 更新前 | 是 |
| updated | updated | updated | 包含组件的 VNode 更新后 | 是 |
| beforeUnmount | beforeUnmount | beforeUnmount | 元素卸载前 | 是 |
| unmounted | unmounted | unmounted | 元素卸载后（最常用于清理） | 是 |
最常用的是：mounted+unmounted
三、自定义指令完整写法对比（三种方式）
方式1：全局注册（main.js / main.ts）
// main.jsimport{createApp}from'vue'importAppfrom'./App.vue'constapp=createApp(App)// 简单示例：v-focus 自动聚焦app.directive('focus',{mounted(el){el.focus()}})// 带清理的示例：v-longpress 长按 500ms 触发app.directive('longpress',{mounted(el,binding){lettimer=nullconststart=(e)=>{if(e.type==='click'&&e.button!==0)returntimer=setTimeout(()=>{binding.value(e)// 执行绑定的函数},500)}constcancel=()=>clearTimeout(timer)el.addEventListener('mousedown',start)el.addEventListener('touchstart',start)el.addEventListener('click',cancel)el.addEventListener('mouseout',cancel)el.addEventListener('touchend',cancel)el.addEventListener('touchcancel',cancel)// 推荐：把清理函数存到 el 上el._longpressCleanup=()=>{el.removeEventListener('mousedown',start)// ... 移除所有监听clearTimeout(timer)}},beforeUnmount(el){// 组件卸载时自动清理if(el._longpressCleanup){el._longpressCleanup()}}})app.mount('#app')方式2：局部注册（<script setup>中使用）
<script setup> import { directive } from 'vue' const vPermission = { mounted(el, binding) { if (!hasPermission(binding.value)) { el.parentNode?.removeChild(el) } } } // 使用方式 defineOptions({ directives: { permission: vPermission } }) </script> <template> <button v-permission="'user:edit'">编辑</button> </template>方式3：最推荐 —— 使用 composable 创建可复用指令
// composables/useFocus.jsimport{onMounted,onBeforeUnmount}from'vue'exportfunctionuseFocus(){constfocusDirective={mounted(el){el.focus()}}return{focusDirective}}<script setup> import { useFocus } from '@/composables/useFocus' const { focusDirective } = useFocus() </script> <template> <input v-focus /> </template>四、经典自定义指令合集（面试 + 项目必备）
| 指令名称 | 功能 | 常用钩子 | 典型实现要点 |
|---|---|---|---|
| v-focus | 自动聚焦 | mounted | el.focus() |
| v-copy | 一键复制内容 | mounted | document.execCommand |
| v-lazy-img | 图片懒加载 | mounted + IntersectionObserver | |
| v-longpress | 长按触发 | mounted + 定时器清理 | |
| v-permission | 按钮级权限控制 | mounted | 判断权限 → remove 或 display:none |
| v-debounce | 输入防抖 | beforeUpdate + updated | |
| v-resize | 监听元素尺寸变化 | mounted | ResizeObserver |
| v-watermark | 页面/元素水印 | mounted | canvas 或 div 叠加 |
| v-draggable | 拖拽移动 | mounted + mousemove | |
| v-loading | 自定义 loading 遮罩 | mounted / updated |
五、总结：面试/项目常问的 10 个问题
- Vue 3 自定义指令比 Vue 2 少了哪些钩子？为什么？
- 自定义指令的
el、binding、vnode、prevNode分别是什么？ - 为什么推荐在
beforeUnmount或unmounted做清理？ - 如何让自定义指令支持修饰符（.prevent .stop 等）？
v-model在自定义组件和自定义指令中的区别？- 组件的
onBeforeUnmount和指令的beforeUnmount执行顺序？ - 如何调试自定义指令（Vue Devtools 是否支持）？
- 自定义指令如何获取组件实例（getCurrentInstance）？
- 为什么很多 UI 库（如 Element Plus）大量使用自定义指令？
- 你写过哪些自定义指令？解决了什么痛点？
有具体想实现的自定义指令（比如 v-permission、v-lazy、v-draggable）需要完整代码示例吗？
或者想看某个生命周期钩子在真实业务中的典型用法？可以直接告诉我～
