1. useEffect 到底帮你干了什么
1.1 useEffect 的“副作用”到底是什么
我记得刚学 React 那会儿，最大的困惑就是：组件明明只是返回一段 JSX，为什么数据还能自己变？后来才明白，渲染只是 React 世界的一半，另一半是副作用（Side Effect）。
所谓副作用，其实就是“渲染之外的一切事情”。比如：
- 从接口拉数据以后 setState
- 监听浏览器的 resize / scroll 事件
- 操作 DOM，比如让输入框自动聚焦
- 启动一个定时器，每 5 秒轮询一次
- 订阅某个全局状态，比如事件总线、WebSocket
这些操作不直接参与 UI 计算，但它们会“影响”组件之外的世界，或者被这个世界影响。而在 React 的函数组件里，你没法像 class 组件那样写componentDidMount/componentDidUpdate/componentWillUnmount三个生命周期方法，函数组件只负责“根据 props 和 state 生成 UI”。于是 React 提供给了我们useEffect，它就是用来承接这些“副作用”的钩子。
我们可以把 React 函数组件想象成一个流水线：输入 props / state → 计算 UI → 输出 DOM → 运行 useEffect。useEffect 是在页面真实渲染到浏览器之后才执行的，这保证了它不会阻塞渲染，也不会在渲染过程中制造混乱。
1.2 useEffect 的运行时机：渲染完成之后才干活
很多新手会把 useEffect 和“渲染过程中执行”搞混，这其实是最大的一处误区。React 的执行顺序是这样的：
- 组件函数被调用，计算出新的虚拟 DOM。
- React 对比新旧虚拟 DOM，决定哪些地方要更新。
- React 把更新提交到真实 DOM。
- 浏览器绘制页面。
- useEffect 的回调函数才在这个时候执行。
也就是说，useEffect 里的代码一定是在“屏幕更新之后”才跑的。如果你在 useEffect 里读取 DOM 的尺寸、坐标、滚动位置，是一定能拿到最新值的。这一点和我当年在 class 组件里写componentDidMount的感受基本一致，只是名字和写法都变了。
这里有一个非常值得注意的细节：useEffect 的默认行为是“每次渲染完成之后都执行一次”。它不像componentDidMount只执行一次，也不像componentDidUpdate只负责更新。它更接近“挂了也管、更新也管、卸载也管”的全能选手。这个特性让它强大，但也让它容易坑人——因为只要你稍微不注意，回调就会莫名其妙执行很多次。
2. 依赖数组：控制 useEffect 执行次数的关键
2.1 为什么要有第二个参数
useEffect 的基本写法是：
useEffect(() => { console.log("每次渲染后都执行"); });如果不传第二个参数，回调会在每一次渲染完成后都执行。对于大部分业务场景来说，这是没必要的浪费。你只是拉一次数据，结果每次输入框敲一个字都要重新拉，服务端压力直接翻倍。
React 为了解决这个问题，设计了依赖数组（dependency array）。它告诉 React：只有在依赖项发生变化的时候，这个 effect 才需要重新执行。
useEffect(() => { console.log("只有当 count 变化时，我才会执行"); }, [count]);这时你可能会问：那不是和componentDidUpdate里手动判断prevProps.count !== count差不多吗？确实，思想是相通的。但在 useEffect 里，依赖数组的可读性和可维护性好太多——代码一眼就能看出这个副作用到底关心什么。
2.2 空依赖数组的真面目
如果你希望副作用只执行一次，也就是实现“挂载后执行一次”的效果，可以传一个空数组：
useEffect(() => { fetchData(); }, []);空数组意味着：这个 effect 不依赖任何值。所以 React 认为它永远不需要重新执行，只在首次挂载后跑一次。
但是这里埋着一个大坑：如果你在空数组里读取了某个 state 或 prop，那么读取到的是首次渲染时的旧值。以后这个值再怎么变，你都不会知道。比如：
const [userId, setUserId] = useState(1); useEffect(() => { fetchUser(userId); // 这里如果传了空数组，userId 永远拿到 1 }, []);这个代码看起来人畜无害，但实际上只要 userId 变成 2、3、4，这个 effect 都不会重新触发。解决办法只有两个：把 userId 加进依赖数组，或者改用 ref 去保存最新值。初学者最常在这翻车，调试的时候以为自己代码写错了，其实是闭包把旧值给“冻住”了。
2.3 依赖数组的对比逻辑
React 判断依赖是否变化，用的不是深比较，而是Object.is 级别的浅比较。这意味着：
- 基本类型数字、字符串、布尔值，直接比较值是否相同。
- 对象、数组、函数，比较的是引用地址，而不是内容。
所以你会看到这种神奇的现象：明明是同一个对象，只是每次渲染都重建了一遍，结果 effect 每次都执行了。
const config = { page: 1 }; // 每次渲染都新建对象 useEffect(() => { loadList(config); }, [config]); // 每次都执行！因为 config 引用变了这其实是 React 官方设计如此，不是 bug。但如果你没理解它，就会写出“无限循环请求数据”的代码。这一点我在后面的调试章节会专门展开。
3. 清理函数：卸载时收手的优雅方案
3.1 为什么需要清理
副作用做了一半，组件却卸载了——这种场景在单页应用里太常见了。比如用户进入详情页，接口数据还没回来，他直接点击返回按钮跑路了。这时候如果接口才回包并 setState，React 会警告甚至导致内存泄漏。
在 useEffect 里，你可以返回一个cleanup 函数，React 会在组件卸载时自动调用它。也可以在依赖变化、effect 重新执行之前，先调用上一次的 cleanup。
useEffect(() => { let timer = setInterval(() => { console.log("还在跑"); }, 1000); return () => { clearInterval(timer); // 组件卸载时，定时器被清掉 }; }, []);这个模式最典型的场景是：
- 清理定时器
- 取消 WebSocket 连接
- 取消订阅事件
- 调用 AbortController 中止请求
3.2 清理时机到底是什么时候
很多人以为 cleanup 只在组件卸载时执行，其实不对。React 的执行规则是：
- 首次挂载时：执行 effect，不执行 cleanup。
- 依赖变化，effect 重新执行前：先执行上一次的 cleanup，再执行新的 effect。
- 组件卸载时：执行最后一次 cleanup。
这意味着 cleanup 不只是“临终告别”，它还担任着“旧任务撤销者”的角色。所以你在 cleanup 里不仅要清理定时器，还要考虑把上一次的请求结果作废，避免 Race Condition。
举个实际场景：搜索框输入关键词，每次输入都发请求。如果没有 cleanup + 防抖，快速输入三个字会同时发出三个请求，而最后显示哪个结果全看接口返回顺序。React 17 以后虽然在严格模式下会主动模拟卸载再挂载，来帮你暴露 cleanup 遗漏问题，但真正的数据竞争还是要靠 AbortController 或者标识位去处理。
useEffect(() => { let isCancel = false; fetchData(keyword).then((data) => { if (!isCancel) { setData(data); } }); return () => { isCancel = true; }; }, [keyword]);这个技巧我几乎每天都在用。它能够保证：只有“最后一次”请求的结果才会被 setState，之前的请求全部被忽略。比单纯用缓存或者防抖都稳。
4. 依赖数组与闭包陷阱：为什么我的 effect 拿不到最新值
4.1 闭包捕获的是渲染快照
useEffect 的回调函数是在某个特定渲染中创建的。它捕获的是那一次渲染时的 props、state 和所有变量的值。这个值就像拍了一张照片，渲染完成后就不变了。
const [count, setCount] = useState(0); useEffect(() => { const timer = setInterval(() => { console.log(count); // 永远打印 0 }, 1000); }, []);你以为每秒都会打印最新的 count，结果打印的一直是 0。原因就是：setInterval 创建时把 count 值 0 捕获进闭包，之后不管 count 怎么变，闭包里的 count 都是 0。
解决方案之一是给 useEffect 加上依赖：
useEffect(() => { const timer = setInterval(() => { console.log(count); }, 1000); return () => clearInterval(timer); }, [count]); // count 每次变化都会重新创建定时器另一种方案是使用useRef保存最新值：
const countRef = useRef(count); countRef.current = count; // 每次渲染后更新 ref useEffect(() => { const timer = setInterval(() => { console.log(countRef.current); // 永远拿最新值 }, 1000); }, []);4.2 闭包陷阱最常见于异步请求和定时器
凡是“延迟执行”的代码，都很容易踩闭包陷阱。比如：
- setTimeout 回调
- setInterval 回调
- Promise.then 回调
- 事件回调函数
因为这些代码并不在渲染阶段立即执行，而是在将来的某个时刻执行。到那时，如果闭包捕获的还是旧值，就会出现“看到的数字不对”的问题。
我们团队有个同事写过一段代码：点击按钮后，1 秒钟后弹出当前输入框内容。因为他在 setTimeout 里直接用了输入框的 value 变量，而 value 是从 props 传进来的。结果每次输入后点击，弹出来的都是上一次输入的内容。排查很久才发现是闭包把旧值捕获了。这个案例非常典型，建议大家在写异步回调时，先问问自己：这个值是不是从依赖数组里传进来的？如果不是，它是不是被旧渲染捕获了？
4.3 依赖数组到底该填什么
这条我非常想强调：依赖数组的意义是“告诉 React 这个 effect 使用了哪些外部值”，而不是“我想让 effect 什么时候去跑”。
很多新手会反过来理解，把依赖数组当成一个“触发开关”。比如 effect 里明明用了user和list，但他只写了[user]。结果数据不对，又觉得 React 有问题。真正规范的做法是：
- 把 effect 里用到的所有 props 和 state 都写进依赖数组。
- 如果用了多个，就填多个。
- 如果不想频繁触发，优先调整逻辑（比如改用 ref），而不是删依赖。
这也就是 React 官方 eslint-plugin-react-hooks 里exhaustive-deps规则检查的内容。按照它的提示去补依赖，99% 的时候都不会出错。
5. 实战案例：一个带防抖的搜索请求
5.1 场景需求与分析
光说不练假把式，我挑一个非常常见的场景来完整捋一遍：搜索框输入关键词，防抖 500ms 后请求接口，展示结果列表，同时考虑竞态和数据过期。
这个需求里隐藏的核心点有三个：
- 每次输入都要更新输入框内容，这是纯 UI 渲染。
- 输入停止 500ms 后才发请求，这是防抖。
- 请求回来后把结果渲染到列表里，这是异步状态更新。
我们会在这一个组件里同时用到 useState、useEffect、useRef，把 useEffect 的几种用法全部串起来。
5.2 第一部分：输入框与基础状态
清晰起见，先把基础结构写出来：
import { useState, useEffect, useRef } from "react"; function SearchBox() { const [keyword, setKeyword] = useState(""); const [result, setResult] = useState([]); const [loading, setLoading] = useState(false); const timerRef = useRef(null); // 输入框变化只做 setState，不在这里触发请求 const handleInput = (e) => { setKeyword(e.target.value); }; return ( <div> <input value={keyword} onChange={handleInput} placeholder="输入关键词搜索" /> {loading ? <p>加载中...</p> : ( <ul> {result.map((item) => <li key={item.id}>{item.name}</li>)} </ul> )} </div> ); }注意我没有把请求逻辑直接写进 handleInput。因为如果写在事件回调里，每次输入都会触发一次请求，还要手动管防抖。这不是 React 推荐的思路——React 的哲学是“数据和渲染驱动副作用”，而不是“事件驱动副作用”。
5.3 第二部分：用 useEffect 实现防抖请求
核心代码来了：
useEffect(() => { if (!keyword.trim()) { setResult([]); return; } // 先清掉上一次的定时器 if (timerRef.current) { clearTimeout(timerRef.current); } timerRef.current = setTimeout(() => { setLoading(true); fetch(`/api/search?q=${keyword}`) .then((res) => res.json()) .then((data) => { setResult(data.list); setLoading(false); }); }, 500); // 组件卸载或 keyword 变化时，清理上一个定时器 return () => { clearTimeout(timerRef.current); }; }, [keyword]);这段代码有几个关键点：
- 防抖逻辑放在 useEffect 里而不是事件里，好处是：不管是通过输入、粘贴、清空，只要 keyword 一变，都会走同一套逻辑。
- 先清上一次定时器再加新的，实现“重新计时”的效果。
- cleanup 里再次清定时器，保证组件卸载或者 keyword 变化时，不会出现上一次的定时器残留。
- setLoading 放在 fetch 之前，请求开始时显示加载态。
这个写法基本已经是业界标准的“useEffect 防抖请求”模板了。直接照着抄完全没问题。
5.4 第三部分：处理竞态与组件卸载
上面代码在大多数情况下能跑，但它还不够稳。如果用户在请求发出后立刻切换关键词，上一次请求回来会把旧结果覆盖到新结果上，屏幕上出现错乱数据。更严重的是，如果组件已经卸载，还在 setState，控制台会报“Can't perform a React state update on an unmounted component”。
我用一个布尔标识位来解决：
useEffect(() => { if (!keyword.trim()) { setResult([]); return; } let ignore = false; // 本次请求是否还有效 if (timerRef.current) { clearTimeout(timerRef.current); } timerRef.current = setTimeout(() => { setLoading(true); fetch(`/api/search?q=${keyword}`) .then((res) => res.json()) .then((data) => { if (!ignore) { setResult(data.list); setLoading(false); } }); }, 500); return () => { clearTimeout(timerRef.current); ignore = true; // 当 keyword 变化或组件卸载时，旧请求结果被忽略 }; }, [keyword]);这里ignore是重中之重。每次 effect 重新执行，都会创建一个新的ignore变量，初始为false。当 cleanup 执行时，它把旧的那次的ignore置为true。这样即便旧请求晚回来，也无法再更新 state。
5.5 最终效果与心得
完整跑通后，这个搜索组件能做到：
- 输入过程中不发请求，停 500ms 后才发；
- 连续输入时只发最后一次请求；
- 组件卸载后不会有 setState 警告；
- 快速切换关键词时，旧请求结果不会覆盖新结果。
我实际测试下来的体感是：在每个输入框场景里，这套模式几乎不需要再改什么。哪怕是做富文本编辑器、筛选条件联动、分页表格搜索，逻辑都是一样的，只是把 fetch 换成你要调用的函数而已。
6. 常见问题排查与性能优化笔记
6.1 常见问题速查表
| 症状 | 原因 | 解决方案 |
|---|---|---|
| useEffect 执行了无数次 | 依赖数组里有对象/数组/函数，每次渲染引用都变 | useMemo / useCallback 稳定引用，或使用 ref 保存 |
| 组件卸载后报 setState 警告 | 异步回调里没有做状态判空 | 用 ignore 标志位，或用 AbortController 中止请求 |
| 定时器拿不到最新值 | 闭包捕获了旧渲染的 state | 用 ref 存最新值，或把依赖加进数组 |
| effect 只在第一次执行 | 空依赖数组[]导致不随更新触发 | 检查是否有需要变化的依赖，补进去 |
| 页面每次都会闪一下 loading | effect 挂在尾部但没有防抖 | 加防抖或拆分状态，避免短暂 loading 闪烁 |
| useEffect 里请求了两次数据（开发模式） | React StrictMode 在开发环境故意挂载两次 | 这是 React 设计的，用于暴露清理遗漏，不用纠结 |
这些问题的根源几乎都集中在“依赖数组”和“闭包”两个概念上。只要把这两个理解透，useEffect 80% 的坑都能自己排查掉。
6.2 性能优化：不要把所有逻辑塞进一个 useEffect
一个常见的坏味道，就是把请求、日志、埋点、事件绑定全塞进同一个 useEffect。这样做的后果是：任何一个依赖变了，所有逻辑都会跟着重跑一遍，浪费资源。
更合理的做法是拆分成多个 useEffect，各管各的事：
// 负责请求数据 useEffect(() => { loadData(); }, [filter]); // 负责埋点 useEffect(() => { trackEvent("filter_changed", filter); }, [filter]); // 负责订阅 useEffect(() => { const off = on("resize", handleResize); return off; }, []);每个 useEffect 遵循“一个职责”的原则，依赖自然清晰，排查问题也方便。不是说 useEffect 拆得越碎越好，而是让“相关的东西尽量聚在一起，无关的东西彻底分开”。
6.3 开发模式下的双重调用
如果你用的是 React 18 的 StrictMode，你会发现在开发环境下，useEffect 的挂载和卸载会被故意执行两次。这不代表你的代码有问题，而是 React 在帮你“彩排”：先卸载一次，考察你的 cleanup 是不是真的收干净了，再重新挂载。
很多人第一次遇到会懵，以为是代码写错了，甚至有人直接把 StrictMode 删掉。我的建议是，保留 StrictMode，让它检查。只有开发模式下暴露出的 cleanup 缺失，在线上才可能变成内存泄漏。平时多花 10 秒看看这些“警告”，线上能省很多事。
6.4 一个小技巧：如果你需要“读取最新值但不想触发执行”
有时候我们想要一个效果：定时器里能拿到最新 state，但又不能因为 state 变化而重建定时器。这时候 useRef 就是最优解。
const latestValue = useRef(value); latestValue.current = value; // 每次渲染同步 useEffect(() => { const timer = setInterval(() => { // 这里可以放心读 latestValue.current }, 1000); return () => clearInterval(timer); }, []);看起来就和前面的“闭包陷阱”解法一样。实际项目中，做轮询、做倒计时、做“读秒器”的时候，这个模式几乎天天用。核心思想就是：ref 相当于一个不会触发渲染的仓库，你只管往里存、往外取。
7. 我踩过的那些坑和一些习惯
7.1 三个印象深刻的翻车案例
先说第一个。有次我在做一个筛选联动面板，需要根据选中的类别重新请求列表。当时我把整个filter对象直接放进依赖数组，然后在请求里读它的字段。代码看起来没问题，但每次筛选一改，effect 会跑两遍。原因是setFilter的时候我把对象整个换了，但 React 的浅比较认为它变了。后来改成把filter.categoryId单独抽出来放进依赖数组，问题立刻消失。
第二个案例是定时器导致的闭包陷阱。我做了一个“剩余时间倒计时”，用 setInterval 每秒减一。因为读取的是初始值，倒计时永远停在同一个数字。这块花了半天才想明白，原来 setInterval 的回调捕获了初始渲染的 state，完全不知道后续变化。后来用 ref 保存时间戳，问题就没了。其实只要记住一句话：定时器里的 state 要看最新值，用 ref。
第三个案例是我们项目里有个组件，useEffect 里订阅了全局事件，但忘了在 cleanup 里退订。结果用户切页面再回来，订阅重复叠加，每次切一次多一条监听，最后页面卡得不行。排查起来很费劲，因为控制台不报错。后来我把所有“订阅类”的 useEffect 统一写成“返回退订函数”的格式，才算根治。
7.2 我现在写 useEffect 的习惯
我给自己定了几个规矩，分享给大家：
- 每个 useEffect 开头先问自己：我不写这个副作用会怎样？如果答案是不会怎样，那就不写。
- 依赖数组不是装饰品，是把所有用到的外部值都写进去。如果写着写着觉得依赖太多、太乱，说明这个副作用该拆了。
- 凡是“持续存在”的东西（事件监听、定时器、订阅），必须写 cleanup。
- 凡是“将来才发生”的东西（请求回调、延时执行），必须做 ignore 保护。
- 尽量不在 useEffect 里写同步逻辑。能算出来的值，就写在渲染主体里，不需要交给副作用。
这些规矩听起来简单，但每一条都有真实事故支撑。照做之后，我几乎没有再被 useEffect 的开销和记忆泄漏坑过。
7.3 useEffect 和 useLayoutEffect 怎么选
最后提一嘴很容易搞混的两兄弟。useEffect 是异步执行，浏览器绘制完成后才跑。useLayoutEffect 是同步执行，在 DOM 更新后、浏览器绘制前跑。如果要在页面绘制前测量 DOM、修改样式、避免闪屏，用 useLayoutEffect 更合适。日常绝大多数场景，比如请求数据、埋点、订阅，用 useEffect 就够了，它的异步特性对性能更友好。
我自己实际用 useLayoutEffect 的场景很有限，基本只在“读取滚动条位置并同步设置某个元素高度”的时候会用到。如果你发现页面有闪烁或跳动，先考虑 useLayoutEffect；如果只是拿数据，就别动它，useEffect 更稳。
8. 一个可以继续扩展的思路
useEffect 的价值不只在 React 项目里，它那套“渲染完成后做副作用的时机”思想，其实在很多框架里都有类似映射，比如 Vue 的 watchEffect、Solid 的 createEffect。理解了 React 的 useEffect，再看这些框架的副作用处理，你会发现套路是一样的：声明一个响应式依赖，当依赖变化时重新执行副作用。
如果你还没试过把那上面的搜索请求再往前推一步，我建议你试试接入AbortController替代之前的布尔 ignore，这样请求如果超时或中途取消，后端也能收到明确的取消信号，网络层面上更干净。这个改动适合你项目请求链路比较成熟、不想靠一个布尔值扛全部责任的时候做。
再或者，你可以把 header、footer、网络请求、日志上报都用自定义 Hook 封装。一个 useFetch 配上 useDebounce，后面每个列表页都能直接复用，省下来的时间自己去喝茶。README 和业务代码都不需要多解释，团队里其他人一看函数名就懂。
9. 最后分享一个实用经验
那次倒计时 bug 解完之后，我对自己定了一条铁律：凡是 useEffect 里出现的 state，我都要强迫自己看一遍依赖数组。如果依赖数组里没它，我一定会停一下，问自己是不是故意的。如果是故意用 ref 绕开，我会在代码旁边写一行注释说明原因，防止同事和未来的我看得一头雾水。
这条铁律帮我少踩了很多坑。说真的，React 的 useEffect 其实不难，难的是在“何时触发”和“为何触发”之间保持清醒。依赖数组是 React 给你的承诺书，闭包是你自己的责任书。前者要如实填写，后者要亲手收尾，两者都做到位，useEffect 就是你的好帮手，而不是那个总在深夜刷新你世界的“周公”。
