Vue 自定义指令卸载时怎么移除事件监听避免重复绑定

Vue 自定义指令一旦在 mounted 中给元素或 window 添加事件监听，就要把它当成一项需要回收的 DOM 资源。最稳妥的做法是：保存创建出来的处理函数和监听选项，在 updated 重绑前先移除旧监听，在 unmounted 中使用同一份引用完成清理。不要在 removeEventListener 里重新写一个看起来相同的箭头函数，因为它不是原来的函数对象。

官方地址：https://vuejs.org/guide/reusability/custom-directives.html

本文只讨论 Vue 3 自定义指令的 mounted、updated、unmounted 关系，以及浏览器事件监听器的配对清理；不把问题改写成组件生命周期或全局状态管理方案。

先识别需要回收的监听资源

一个监听是否能被正确移除，至少取决于四个信息：事件目标、事件类型、处理函数引用，以及 capture 是否一致。比如指令把监听加在 window 上，卸载时却对 el 调用移除，即使函数引用正确也不会清掉目标上的监听。

Vue 官方把自定义指令定位为复用低层 DOM 操作的机制，并提供与组件相似的钩子。mounted 适合建立监听，updated 适合处理绑定值变化，unmounted 则是释放该指令占用资源的最后入口。

用同一处理函数完成绑定和卸载

下面的指令监听窗口尺寸，并把当前配置放进元素上的私有状态。这里使用 Symbol 只是为了降低属性名冲突风险；它不改变 Vue 的生命周期，也不把监听器泄漏到组件外部。

const listenerState = Symbol('vMeasureListener')

function createHandler(el, label) {
  // 返回可保存、可复用的同一个函数对象，卸载时必须拿它移除
  return () => {
    el.dataset.measureLabel = String(label ?? '')
  }
}

const vMeasure = {
  mounted(el, binding) {
    // mounted 只建立一次监听，并把 target、handler、capture 一起保存
    const state = {
      target: window,
      type: 'resize',
      capture: false,
      handler: createHandler(el, binding.value)
    }
    el[listenerState] = state
    state.target.addEventListener(state.type, state.handler, {
      capture: state.capture,
      passive: true
    })
  },

  updated(el, binding) {
    const state = el[listenerState]
    // 没有 mounted 状态时不猜测，避免更新阶段产生孤儿监听
    if (!state || binding.value === binding.oldValue) return

    // 先移除旧引用，再创建新引用，避免每次更新都叠加一个监听
    state.target.removeEventListener(state.type, state.handler, {
      capture: state.capture
    })
    state.handler = createHandler(el, binding.value)
    state.target.addEventListener(state.type, state.handler, {
      capture: state.capture,
      passive: true
    })
  },

  unmounted(el) {
    const state = el[listenerState]
    // 卸载要使用原来的 target、type、handler 和 capture
    if (!state) return
    state.target.removeEventListener(state.type, state.handler, {
      capture: state.capture
    })
    delete el[listenerState]
  }
}

这段代码的关键不是 Symbol，而是 state.handler 从注册到移除始终指向同一个函数。passive 只影响监听行为，移除时真正影响匹配的是 capture；实践中仍建议把选项集中保存，避免绑定和卸载时写出不同配置。

重复绑定的风险如何分级排查

把问题当成一次小型资源威胁建模，会比只看“页面有没有报错”更可靠。第一类风险是匿名函数：addEventListener('resize', () => {}) 后再写一个新的箭头函数，两个函数引用不同，旧监听仍然存在。第二类风险是 capture 不一致：注册时为 true，移除时传 false，这次移除不会命中。

第三类风险来自 updated。绑定值变化并不意味着 Vue 会替你清理浏览器原生监听；如果每次更新都直接 addEventListener，同一个元素可能一次事件触发多次。第四类风险是监听目标变化，例如某次把监听放到 document，卸载时却固定对 window 清理。目标也必须跟着状态保存。

如果业务只需要一次性处理，也可以使用 once，让浏览器在回调执行后自动移除；但只要指令仍可能更新或卸载，就不要把 once 当成完整的生命周期清理方案。

卸载前后的核对清单

排查“组件切换回来后事件触发两次”时，按下面顺序记录一次即可：

• 确认 mounted 是否只创建一份状态，以及状态是否绑定在当前元素上。
• 确认 updated 是否只在配置真的变化时重绑，并且先移除旧函数。
• 确认 unmounted 使用的 target、type、handler、capture 与注册时一致。
• 确认清理完成后删除临时状态，下一次挂载重新建立一套资源。

一句话总结：Vue 负责调用自定义指令的生命周期钩子，浏览器不会替你记住事件处理函数。把监听资源集中保存，并让 mounted、updated、unmounted 共用这份状态，就能把重复绑定和卸载残留控制在同一条清理路径里。

常见问题

为什么 removeEventListener 写了同样的箭头函数仍然无效？ 因为每次创建的匿名函数都是不同对象，必须保存首次注册的函数引用。

移除监听时要完整传入 passive 吗？ 匹配监听时关键是事件类型、函数引用和 capture；为了可读性，建议仍从同一份状态中传入一致的选项。

updated 一定要移除再绑定吗？ 只有监听逻辑或配置确实变化时才需要重绑；如果处理函数不变，可以跳过这一步，但 unmounted 仍要清理。