你有一个搜索框。使用者输入 react hooks你的组件就在每一次按键上发一个 API 请求——一个查询发了十一个请求，其中十个在返回时早就过期了。所有人都会想到的修法是防抖等输入停下来再发一次。怎么说呢，而所有人都会写错的修法。是在组件里用 setTimeout 手写这个防抖——过期闭包、漏掉的清理、re-render 抖动，会悄悄把它弄坏。

useDebounce 就是把这件事做对的那个 hook。这篇文章讲清楚你真正需要的两种形态——给值做防抖、给回调做防抖——什么时候用哪个，还有怎么 cancel或 flush待处理的调用。这里写的全是真实的 @reactuses/core API，SSR 安全且带类型。

为什么不直接用 setTimeout？

防抖本身很简单：把一个函数推迟到一段安静期之后再执行，每来一次新调用就重置计时器。难的是在React 组件里做这件事。下面是最直觉的写法，它带了三个 bug：

function Search {
const = useState;const timer = useRef;其实，function handleChange {
const value = e.target.value;setQuery，clearTimeout;timer.current = setTimeout => {
fetchResults;// 🐛 见下文
},/* wait */);}
return ;}

1. 卸载时会泄漏。 如果组件在计时器待处理时卸载。回调依然会在 ms 后触发——往往是给一个已经消失的组件 setState，或者为使用者早已离开的页面打 API。按理说，
2. 它会捕获过期的值。 一旦你防抖的是不是原始事件值，而是第二个 state、一个 prop、一个派生值——闭包冻结的是计时器设置时的它们。而不是触发时
3. 它会到处复制。  每个需要防抖的地方都重写一遍 + 每份拷贝都是一次忘掉清理机会。

A hook in one place fixes all three problems. ReactUse provides two hooks internally based on battle‑tested so edge cases are already handled.

useDebounce —— 给值做防抖

The most common scenario: you have a fast‑changing value and you want its second copy— a lagging duplicate—updated only after everything stabilizes. That copy is what you feed expensive calculations.

import { useState } from 'react';import { useDebounce } from '@reactuses/core';function Search {
const = useState;const debouncedQuery = useDebounce;useEffect => {
if return;fetchResults;},)，return (
 setQuery}
placeholder="搜索…"
/>
)，}

The signature is useDebounce ,returning debounced value with same type as input:

const debounced = useDebounce;

The input ) updates on every key press so controlled input stays in sync—this is raw DOM value you type into. The output ) lags until user stops typing for ms before catching up—this is what you put into an effect dependency array. The API now fires once per pause instead of per keystroke while your input never feels blocked because you're typing into raw value.

This pattern—fast UI value + debounced side‑effect value—is all re is to it. Keep m separate variables and everything else falls into place.

If what you want to debounce is an action with parameters—a save draft call。a logging event,a resize handler—rar than a state change itself,n .

import { useDebounceFn } from '@reactuses/core';function Editor {
const { run } = useDebounceFn(
=> saveDraft,/* wait */
);return (
 run}
/>
);}

returns an object with three members:

"const { run。cancel,flush } = useDebounceFn;" />

• run: Debounced function wrapper. Call it as often as needed;it will execute fn only after stop‑typing for *wait* ms. All arguments are forwarded intact.
• cancel: Discards any pending invocation—no side effects.
• flush: Immediately triggers pending invocation instead of waiting for timer expiry.

The key point: 's callback always uses your latest fn implementation because it’s stored in a ref internally so even if wrapper was created once it never expires—no “docId” closure issue from a plain setTimeout version. And this hook automatically cancels pending calls when unmounted so no lingering bugs.

tsx function CommentBox { const { run: autosave。cancel,flush } = useDebounceFn( =>saveDraft,/* wait */ );

return ( <> {/* 使用者点了「发布」——立刻持久化，别等那秒 /} {/ 使用者点了「丢弃」——扔掉待处理自动保存 */} );}

flush guarantees that any flying draft is saved before posting data downstream while cancel ensures discarded drafts never get auto‑saved afterward—all by calling just once.

A quick decision rule:

• If you're debouncing something that will be read elsewhere as state — search query,filter criteria or chart slider values — choose useDebounce. You need a lagging value.
• If you're debouncing an action with arguments — auto‑save or logging — choose useDebounceFn. You need a lagging function。plus optional cancel/flush control.
• If you find yourself creating a state solely for debouncing n immediately triggering an effect that consumes that state,useDebounceFn is usually more direct.

The third optional argument passes straight through to Lodash.debounce providing full control over edge behavior:

ts // example options: const debouncedValue = useDebounce(value,/* wait */,{ leading: false,trailing: true,maxWait : /* seconds */,} );

Two knobs worth knowing:

• leading:true : Fires immediately on first call n applies debounce logic reafter – great for interactions where first click should feel instant while rapid repeats are suppressed .
• maxWait: Caps total delay – under pure trailing debounce a ten‑second burst of typing would yield zero updates until stopping. Setting maxWait: forces at least one update per second during continuous bursts – making your search box feel alive instead of frozen.

Both hooks are safe during server‑side rendering—y never touch window,document,or browser timers during render phase because ir work lives inside effects which React never runs server‑side. Drop m into Next.js/Remix/Astro components without worrying about typeof window guards or hydration warnings.\

In ReactUse re are three close relatives by how y limit things and which shape y offer:

If you’re dealing with continuous gestures needing real‑time feedback,throttle keeps things moving at regular intervals instead of waiting for silence.\

• A handwritten setTimeout debouncer in component comes preloaded with three bugs:
  • No cleanup when component unmounts → leaks;怎么说呢，
  • Catches stale closures → wrong values;
  \t\t\t\t\t \t\t\t\t\t \t\t \t •\t duplicate boilerplate → increased risk of missing cleanup. <\/span> <\/ul> <\/ul> ● @reactuses/core\u0027s useDebouncy provides two flavors: \u2028• Value Debouncer – returns delayed copy of your fast changing state. \u2028• Callback Debouncer – returns wrapper around your action plus run/cancel/flush utilities. \u2028Both automatically clean up when component unmounts and always invoke latest callback implementation. \u2028Using flush lets you commit pending work immediately . Using cancel discards pending work . \u2028Third argument exposes Lodash debounce options giving fine control over timing. \u2028Both hooks are SSR safe and pair nicely with {Throttling}\u0027s family for fixed frequency scenarios. <\/ul> P.S.这方面，Grab m from @reactuses/core today and ditch your own clearTimeout boilerplate forever!