在 React 或 Vue 项目中封装使用 JS 节流防抖

在高频交互场景（如实时搜索联想、窗口缩放适配、页面滚动监听与表单重复提交）中，JavaScript 防抖（Debounce）与节流（Throttle）是控制函数触发频率、减少冗余计算与接口压力的核心技术手段。但在现代前端框架中，如果只是简单地将原生防抖节流函数写在组件内部，往往会因为组件重新渲染导致实例被重新创建而失效，或者因为闭包捕获了陈旧的状态变量而读不到最新的数据。本文将直接从原生实现的底层逻辑切入，深入分析框架渲染周期与闭包机制的冲突原因，并分别针对 React 和 Vue 3 给出高可用、具备生命周期自动清理的封装方案与场景选型指南。

一、防抖与节流的核心差异与机制解析

防抖与节流的目标都是降低高频事件的触发频率，但两者的控制逻辑截然不同：

• 防抖（Debounce）：将高频操作“合并为一次执行”。只要在等待周期 delay 内事件再次被触发，计时器就会被重置并重新倒计时，只有当用户完全停止操作并静止满 delay 时间后，目标函数才会真正被调用一次。典型应用场景包括：输入框实时自动补全、窗口 resize 结束后的重新排版、富文本编辑器的自动保存。
• 节流（Throttle）：将高频操作“平摊为固定周期执行”。在设定的时间窗口 interval 内，无论事件被高频触发了多少次，目标函数都严格按照固定的时间间隔均匀执行一次。典型应用场景包括：页面滚动 scroll 触底加载、鼠标移动 mousemove 坐标轨迹计算、视频播放进度实时同步。

理解两者机制的最直接方式是观察原生的 JavaScript 闭包实现。一个标准且健壮的原生防抖函数需要支持定时器清理与即时传参：

// 基础原生防抖函数
function debounce(fn, delay) {
  let timer = null;

  function debounced(...args) {
    // 每次触发，清除上一次正在倒计时的定时器
    if (timer) {
      clearTimeout(timer);
    }
    // 开启新的倒计时
    timer = setTimeout(() => {
      fn.apply(this, args);
      timer = null;
    }, delay);
  }

  // 提供主动取消能力
  debounced.cancel = function() {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
  };

  return debounced;
}

而基于时间戳与定时器混合的节流实现，既能保证第一次触发时立刻响应（Leading），又能确保停止触发后最后一次动作不会被遗漏（Trailing）：

// 基础原生节流函数
function throttle(fn, interval) {
  let lastTime = 0;
  let timer = null;

  function throttled(...args) {
    const now = Date.now();
    const remaining = interval - (now - lastTime);

    // 如果已超出时间窗口，立即执行
    if (remaining <= 0) {
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      lastTime = now;
      fn.apply(this, args);
    } else if (!timer) {
      // 处于窗口期内，延迟到窗口结束时补足执行尾部事件
      timer = setTimeout(() => {
        lastTime = Date.now();
        timer = null;
        fn.apply(this, args);
      }, remaining);
    }
  }

  throttled.cancel = function() {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    lastTime = 0;
  };

  return throttled;
}

二、为什么直接在框架组件内调用原生防抖节流会失效？

初学者在 React 或 Vue 项目中常常尝试直接将 debounce 套在事件处理函数上，例如在 React 函数组件内写下 const handleSearch = debounce(searchApi, 300)。在实际运行中，这种写法会暴露出两个极其隐蔽的致命问题：

1. React 重新渲染导致实例被重复创建

React 函数组件的本质是一个纯函数，每一次 state 或 props 的改变都会触发整个函数体从头到尾重新执行（Re-render）。如果在函数体作用域内直接执行 debounce(fn, 300)，每一次重新渲染都会生成一个**全新的防抖函数实例**及其**全新的闭包上下文**。

这意味着：用户输入第 1 个字符，创建了防抖实例 A 并开启计时；紧接着输入第 2 个字符触发了组件渲染，函数重新执行创建了防抖实例 B。此时实例 B 内部的 timer 为空，根本无法清除实例 A 中正在运行的定时器。结果是，每一次按键生成的独立定时器都会各自在 300ms 后准时触发，防抖功能彻底崩溃，接口请求完全没有被合并。

2. 简单包裹 useCallback 导致的陈旧闭包陷阱（Stale Closure）

有的开发者为了避免每次渲染都创建新函数，会尝试使用 useCallback(debounce(fn, 300), [])。将依赖项数组设置为空数组 [] 确实能够保证 handleSearch 在多次渲染间指向同一个内存地址，但却引发了更难排查的“陈旧闭包”漏洞：

如果回调函数 fn 内部依赖了当前组件的某项 state（例如搜索筛选分类 category），由于 useCallback 仅在组件初次挂载时初始化了一次闭包，fn 内部捕获的永远是首屏渲染时的初始快照。哪怕后续界面上的分类下拉框已经切换，当延迟执行的搜索请求触发时，读取到的 category 依然是默认值，导致发出的业务请求携带了陈旧参数。

3. Vue 3 中的作用域解耦与组件卸载清理隐患

在 Vue 3 的 <script setup> 中，虽然代码块只会在组件实例化时执行一次，解决了“每次渲染都重复创建防抖实例”的问题，但如果直接调用原生防抖，依然存在两项重大缺陷：

1. 缺乏生命周期联动：当用户快速切换路由或关闭弹出层使组件卸载时，后台挂起的定时器依然在继续倒计时。倒计时结束后，回调函数如果尝试更新组件内的 ref 变量，不仅会产生多余的网络 IO，还会造成内存泄漏。
2. 无法与响应式系统直接绑定：模板中的 v-model 需要与响应式变量无缝协同，原生防抖只能作用于具体的事件方法，无法直接封装成防抖的 ref 数据流。

三、在 React 中封装生产级自定义 Hook

在 React 中优雅解决上述问题的破局核心在于：**使用 useRef 持有最新的业务回调，使用 useMemo（或 useRef）维持稳定的执行器引用，并在 useEffect 的卸载函数中提供自动销毁。**

1. 封装通用防抖 Hook：useDebounceFn

该 Hook 接收业务回调函数与配置项，返回一个引用地址永不改变的触发函数 run，并附带 cancel 与 flush 控制方法：

import { useRef, useEffect, useMemo } from 'react';

export interface DebounceOptions {
  delay?: number;
  immediate?: boolean;
}

export function useDebounceFn<T extends (...args: any[]) => any>(
  fn: T,
  options: DebounceOptions = {}
) {
  const { delay = 300, immediate = false } = options;

  // 1. 使用 ref 始终同步保存最新回调，彻底斩断闭包过期
  const fnRef = useRef(fn);
  fnRef.current = fn;

  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);

  // 2. 稳定执行器对象：引用在组件生命周期内保持稳定
  const executor = useMemo(() => {
    const run = (...args: Parameters<T>) => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }

      if (immediate && !timerRef.current) {
        fnRef.current(...args);
      }

      timerRef.current = setTimeout(() => {
        if (!immediate) {
          fnRef.current(...args);
        }
        timerRef.current = null;
      }, delay);
    };

    const cancel = () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
        timerRef.current = null;
      }
    };

    const flush = (...args: Parameters<T>) => {
      cancel();
      fnRef.current(...args);
    };

    return { run, cancel, flush };
  }, [delay, immediate]);

  // 3. 宿主生命周期守卫：组件卸载时自动清理定时器，避免内存泄漏
  useEffect(() => {
    return () => {
      executor.cancel();
    };
  }, [executor]);

  return executor;
}

2. 封装通用节流 Hook：useThrottleFn

节流 Hook 沿用相同的设计哲学，通过记录上一次执行时间戳 lastExecTimeRef 来维持节流周期的准确性：

export function useThrottleFn<T extends (...args: any[]) => any>(
  fn: T,
  options: { interval?: number } = {}
) {
  const { interval = 300 } = options;

  const fnRef = useRef(fn);
  fnRef.current = fn;

  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const lastExecTimeRef = useRef<number>(0);

  const executor = useMemo(() => {
    const run = (...args: Parameters<T>) => {
      const now = Date.now();
      const remaining = interval - (now - lastExecTimeRef.current);

      if (remaining <= 0) {
        if (timerRef.current) {
          clearTimeout(timerRef.current);
          timerRef.current = null;
        }
        lastExecTimeRef.current = now;
        fnRef.current(...args);
      } else if (!timerRef.current) {
        timerRef.current = setTimeout(() => {
          lastExecTimeRef.current = Date.now();
          timerRef.current = null;
          fnRef.current(...args);
        }, remaining);
      }
    };

    const cancel = () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
        timerRef.current = null;
      }
      lastExecTimeRef.current = 0;
    };

    return { run, cancel };
  }, [interval]);

  useEffect(() => {
    return () => {
      executor.cancel();
    };
  }, [executor]);

  return executor;
}

3. React 组件实际调用示例

在业务组件中使用封装好的 Hook 时，直接将返回的 run 赋给事件即可，既具备抗重渲染能力，又能安全获取组件最新的状态值：

import React, { useState } from 'react';
import { useDebounceFn } from './useDebounceFn';

export function SearchBox() {
  const [keyword, setKeyword] = useState('');
  const [selectedTag, setSelectedTag] = useState('all');

  // 即使 selectedTag 频繁改变，searchApi 也能准确读取到最新的 selectedTag
  const { run: debouncedSearch } = useDebounceFn((text: string) => {
    console.log('执行远程搜索:', text, '当前分类标签:', selectedTag);
    // 实际远程接口调用逻辑...
  }, { delay: 350 });

  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setKeyword(value);
    debouncedSearch(value); // 触发稳定引用防抖
  };

  return (
    <div>
      <input value={keyword} onChange={handleInputChange} placeholder="输入关键词搜索..." />
      <button onClick={() => setSelectedTag('tech')}>切换标签</button>
    </div>
  );
}

四、在 Vue 3 中封装高质量 Composable 函数

在 Vue 3 Composition API 中，封装的目标是在提供防抖执行能力的同时，结合 Vue 响应式系统的生命周期钩子（onBeforeUnmount 或 onScopeDispose）实现资源的自动回收。此外，Vue 3 官方提供了底层 API customRef，允许我们直接创建自带防抖能力的响应式变量。

1. 封装通用防抖与节流 Composable：useDebounceFn

在 Vue 3 中实现函数防抖，利用 onBeforeUnmount 确保组件在页面离开时自动销毁未完成的定时器：

import { onBeforeUnmount } from 'vue';

export function useDebounceFn<T extends (...args: any[]) => any>(
  fn: T,
  delay: number = 300,
  immediate: boolean = false
) {
  let timer: ReturnType<typeof setTimeout> | null = null;

  const run = (...args: Parameters<T>) => {
    if (timer) {
      clearTimeout(timer);
    }

    if (immediate && !timer) {
      fn(...args);
    }

    timer = setTimeout(() => {
      if (!immediate) {
        fn(...args);
      }
      timer = null;
    }, delay);
  };

  const cancel = () => {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
  };

  // 自动绑定当前组件作用域的销毁逻辑
  onBeforeUnmount(() => {
    cancel();
  });

  return { run, cancel };
}

2. 基于 customRef 封装响应式值防抖：useDebouncedRef

当需要将输入框通过 v-model 绑定到一个延迟响应的变量时，直接封装响应式 Ref 是最契合 Vue 设计哲学的方式。customRef 接收一个工厂函数，提供 track（依赖收集）和 trigger（派发更新）控制：

import { customRef } from 'vue';

export function useDebouncedRef<T>(initialValue: T, delay: number = 300) {
  let timer: ReturnType<typeof setTimeout> | null = null;
  let value = initialValue;

  return customRef((track, trigger) => {
    return {
      get() {
        track(); // 通知 Vue 收集对此属性的依赖
        return value;
      },
      set(newValue: T) {
        if (timer) {
          clearTimeout(timer);
        }
        // 延时设置并派发响应式更新
        timer = setTimeout(() => {
          value = newValue;
          trigger(); // 延时满后触发视图或计算属性的更新
          timer = null;
        }, delay);
      }
    };
  });
}

3. Vue 3 业务组件调用示例

在单文件组件中使用 useDebouncedRef 和 useDebounceFn：

<script setup lang="ts">
import { watch } from 'vue';
import { useDebouncedRef } from './useDebouncedRef';
import { useDebounceFn } from './useDebounceFn';

// 1. 响应式防抖变量：与输入框双向绑定，输入停止 400ms 后才触发响应更新
const searchKeyword = useDebouncedRef('', 400);

watch(searchKeyword, (newVal) => {
  if (newVal) {
    console.log('触发防抖查询:', newVal);
  }
});

// 2. 函数级节流/防抖：用于按钮高频点击或滚动监听
const { run: handleSubmit } = useDebounceFn(() => {
  console.log('提交表单数据，防止连击');
}, 300, true); // immediate = true 立即执行首次
</script>

<template>
  <div class="search-panel">
    <input v-model="searchKeyword" placeholder="输入搜索内容..." />
    <button @click="handleSubmit">提交</button>
  </div>
</template>

五、常见混淆说法辨析与参数边界处理

前置执行（Leading）与后置执行（Trailing）的控制边界

在设计防抖与节流时，必须明确区分以下两类业务需求：

• 后置执行（Trailing）：默认模式。事件停止触发后才执行，适用于文本联想、输入检验与窗口排版重绘。
• 前置执行（Leading）：初次触发立刻执行，后续在冷却期内的重复点击全部静默拦截。适用于防止用户双击提交表单、点赞按钮防暴力点击等场景。

六、技术选型决策树与实践落地清单

为了在实际业务开发中能够快速判断并规范化落地，可参考以下选型决策流程与关键检查项：

下表对比了防抖与节流在不同技术栈下的关键实施要点与注意事项：

技术维度	防抖（Debounce）	节流（Throttle）
本质特征	事件静止后触发，合并多次操作为一次	以恒定时间节奏放行，平摊高频峰值
典型业务场景	搜索建议输入、窗口缩放、表单即时验证	滚动加载、拖拽位移、高频监控日志上报
React 落地关键	useRef 缓存回调，useMemo 维持实例，useEffect 卸载调用 cancel	useRef 同步更新时间戳与 timer，避免因 state 变更重建导致节流周期失效
Vue 3 落地关键	事件方法用 useDebounceFn；数据流绑定用 customRef	使用 useThrottleFn，在 onBeforeUnmount 阶段主动释放定时器
异常边界防护	路由跳转前提供 cancel() 取消无意义查询，必要时支持 flush()	组件被 KeepAlive 缓存或销毁时，确保未结的尾部执行被妥善重置

总结而言，在现代前端组件化开发中，处理节流与防抖的关键已经超越了单纯的 JavaScript 定时器算法，核心在于**理解并顺应框架的生命周期模型**。在 React 中抓住 useRef 这个持久化引用容器，在 Vue 3 中善用 Composition API 的单一初始化与自动注销特性，即可构建出性能优异、逻辑严谨且易于维护的高质量前端工程代码。