在前端开发的漫长旅途中，我们经常会遇到这样一种尴尬的境地：手里握着一大把在 Vue2 时代打磨得锃光瓦亮的自定义指令，兴致勃勃地准备迁移到 Vue3 项目时却发现控制台里报错红了一片。那种心情，简直就像是刚买了一辆新车，却发现旧车库的钥匙怎么也插不进去。其实这并不是你的代码写错了而是 Vue3 在底层设计上Zuo了一次“大换血”，特别是对于直接操作 DOM 的自定义指令来说变化可谓是翻天覆地。

今天我们就来好好聊聊这个让人又爱又恨的话题。别担心，我会用Zui接地气的方式，带你一步步拆解 Vue2 和 Vue3 在自定义指令上的那些“爱恨情仇”，顺便分享一些实战中的避坑指南。毕竟谁不想在代码迁移的时候少掉几根头发呢？

在深入代码细节之前，我们先得明白，为什么 Vue 官方dou推荐使用组件化开发了我们还需要自定义指令这种“古老”的东西？老实说Vue 的组件系统确实非常强大，v-modelv-show 这些内置指令也覆盖了大部分日常需求。但是现实世界的业务逻辑总是充满了各种奇奇怪怪的边缘情况。

有时候，我们需要在页面加载时自动让某个输入框获得焦点；有时候，我们需要根据用户的权限动态地隐藏某个按钮；还有时候，我们需要给图片加个懒加载，或者给某个高频点击的按钮加个防抖。这些需求Ru果全dou塞进组件的 mounted 或者 updated 生命周期里代码hen快就会变成一团乱麻，维护起来简直是噩梦。

这时候，自定义指令就像是那个在混乱中挺身而出的超级英雄。它允许我们将这些底层的 DOM 操作逻辑封装起来变成一个简单的 v-xxx 标签。这不仅让代码kan起来geng加清爽，geng重要的是它实现了逻辑的复用。正如那句老话所说术业有专攻，组件负责数据和视图的绑定，而自定义指令则负责那些脏活累活——直接操作 DOM。

好了重头戏来了。Vue2 和 Vue3 Zui大的区别，其实就藏在那些钩子函数的名字里。Ru果你习惯了 Vue2 的写法，刚开始kan Vue3 的文档可Neng会觉得有点晕，但只要你理解了其中的逻辑，就会发现其实换汤不换药。

在 Vue2 的世界里一个指令的生命周期主要由五个钩子函数组成。那时候我们关注的是指令与元素“绑定”和“插入”的过程。

bind这是指令第一次绑定到元素时调用的。这时候元素虽然还在娘胎里但我们Ke以在这里Zuo一些初始化的准备工作，比如一次性的事件监听设置。

inserted这是Zui常用的钩子之一。当被绑定的元素真正插入到父节点时调用。这时候，你Ke以放心地去操作 DOM，比如调用 el.focus，因为元素Yi经在页面上了。

update当组件的 VNode geng新时调用。但是要注意，这时候子组件可Neng还没geng新完。

componentUpdated这是指令所在的组件及其子组件全部geng新完成后调用的。Ru果你需要根据数据的变化来geng新 DOM 样式，这里是个好地方。

unbind这就是“临终关怀”了。当指令与元素解绑时调用，记得在这里清理定时器、移除事件监听，不然内存泄漏会找上门的。

到了 Vue3，尤大神为了保持 API 的一致性，将指令的生命周期钩子改得和组件的生命周期一模一样。这其实是个hen棒的改进，因为你不需要在脑子里切换两套逻辑了。

created对应 Vue2 的 bind。指令绑定到元素后立即调用，元素还没挂载。

beforeMount元素即将被挂载到 DOM 前。

mounted对应 Vue2 的 inserted。元素Yi经挂载完毕，Ke以开始你的表演了。

beforeUpdate对应 Vue2 的 update。geng新前调用。

updated对应 Vue2 的 componentUpdated。geng新后调用。

beforeUnmount卸载前。

unmounted对应 Vue2 的 unbind。卸载后清理现场。

kan到这里你是不是觉得松了一口气？其实只要把名字对应上，逻辑基本是不用动的。这种命名方式确实geng符合直觉，特别是对于刚入门的新手来说学习成本大大降低了。

除了钩子函数，注册指令的方式也发生了一些微妙的变化。在 Vue2 中，我们习惯直接在 Vue 构造函数上动手脚，而在 Vue3 中，一切dou变成了“实例”的方法。

回想一下 Vue2 的日子，我们要注册一个全局指令，通常会这么Zuo：

// Vue2 的经典写法
import Vue from 'vue'
Vue.directive('focus', {
  inserted {
    el.focus
  }
})

而在 Vue3 中，由于没有了全局的 Vue 对象，我们通过 createApp 创建的实例来注册：

// Vue3 的现代化写法
import { createApp } from 'vue'
const app = createApp
app.directive('focus', {
  mounted {
    el.focus
  }
})

这其实体现了 Vue3 geng加模块化的设计思想。每个应用实例dou是独立的，不会互相污染。这简直是救命稻草。

在局部注册方面Vue3 的组合式 API带来了一些非常有意思的“黑魔法”。在 Vue2 或者 Vue3 的 Options API 中，我们还是老老实实地在 directives 选项里写：

export default {
  directives: {
    focus: {
      mounted {
        el.focus
      }
    }
  }
}

但是！在

这种写法不仅减少了代码量，还让逻辑geng加集中。对于喜欢用 Composition API 的朋友来说这绝对是个福音。

光说不练假把式。下面我们来kan几个具体的例子，kankan如何在实战中适配这两个版本。我会尽量把代码写得详细一点，毕竟大家dou是直接复制粘贴党。

这是一个Zui经典的入门案例。虽然 HTML 有 autofocus 属性，但在 SPA中，由于路由切换和 DOM 的动态渲染，原生属性经常失效。这时候，自定义指令就派上用场了。

Vue2 版本：

Vue.directive('focus', {
  inserted {
    // 必须在 inserted 中调用，因为这时候元素才在 DOM 树中
    el.focus
  }
})

Vue3 版本：

app.directive('focus', {
  mounted {
    // Vue3 中对应的是 mounted
    el.focus
  }
})

在后台管理系统中，根据用户权限显示或隐藏按钮是家常便饭。虽然用 v-if 也NengZuo，但写起来太啰嗦了。不如封装一个指令，把权限码传进去，自动处理。

Vue3 实战：

import { useUserStore } from '@/stores/user'
app.directive('permission', {
  mounted {
    const userStore = useUserStore
    const requiredPermission = binding.value // 比如 'user:delete'
    // Ru果用户权限列表里没有这个权限，直接移除元素
    if ) {
      // 加个 ? 防止父节点不存在时报错
      el.parentNode?.removeChild
    }
  }
})

在模板中使用：删除用户

const vDebounce = {
  mounted {
    let timer
    // 获取传入的参数，比如函数和延迟时间
    const { func, delay = 300 } = binding.value
    el.addEventListener => {
      if  clearTimeout
      timer = setTimeout => {
        func
      }, delay)
    })
    // 把 timer 挂载到 el 上，方便 unmounted 时清理
    el._timer = timer
  },
  unmounted {
    // 记得清理，不然内存泄漏会找上门
    if  clearTimeout
  }
}