React useEffect闭包陷阱：一个值卡了我两天，最后发现是渲染快照在作怪

两天前我在项目里排查一个诡异的 bug：一个仪表盘页面的数据自动刷新功能，每隔 10 秒拉一次接口，如果后端返回 500 就弹 toast 提示"服务器异常，正在重试"，同时把重试次数 +1。结果，toast 上的重试次数永远显示"0"，不管实际重试了多少次。我一开始以为是后端没返回正确的状态码。打开 DevTools 看 Network 面板，请求确实在发，而且后端日志也证实连续返回了好几个 500。问题出在前端------重试次数这个 state 压根没更新到 UI 上。我又翻了一遍 console，没有报错，没有 warning，静悄悄的。就好像这段代码在另一个平行宇宙里正常运行着。

又花了半个小时，我在 setInterval 回调里加了个 console.log('retryCount:', retryCount)，一看输出------永远是 0。这才反应过来：我又双叒叕踩到 React 的闭包陷阱了。这个坑我之前明明写过笔记，还专门发过一篇内部 wiki。结果在自己写的生产代码里还是犯了。人果然记不住自己真正理解过的东西，只有在上面栽过跟头才算数。趁这次痛定思痛，把这个问题从头到尾理一遍。不只是写"怎么修"，更想聊聊为什么这个坑这么隐蔽、为什么修好了还会再踩。

那个该死的 setInterval

先看 bug 代码：

scss 复制代码

function DataDashboard() {
  const [retryCount, setRetryCount] = useState(0);
  const [data, setData] = useState(null);

  useEffect(() => {
    const timer = setInterval(async () => {
      try {
        const res = await fetch('/api/dashboard');
        if (res.status === 500) {
          // 这里读到的 retryCount 永远是 0
          showToast(`服务器异常，正在重试（第${retryCount + 1}次）`);
          setRetryCount(retryCount + 1); // 永远设成 1
        } else {
          const json = await res.json();
          setData(json);
          setRetryCount(0);
        }
      } catch (e) {
        console.error('refresh failed:', e);
      }
    }, 10000);

    return () => clearInterval(timer);
  }, []); // 依赖数组空的

  return <div>...</div>;
}

看着挺合理的对吧？定时器每 10 秒跑一次，500 了就重试计数 +1。问题出在 useEffect 的依赖数组是空的 []。这意味着 effect 只在组件挂载时执行一次，而 setInterval 里的回调函数在那一刻被创建，捕获了当时 retryCount 的值------也就是 0。之后每次定时器触发，回调里读到的 retryCount 永远是那个被闭包锁死的 0。所以 setRetryCount(0 + 1) 永远等于 1，toast 上的文字也永远显示"第1次"。这就是"闭包陷阱"的核心：effect 里引用的 state 不是实时值，是那次渲染的快照。每次 React 重新渲染组件时，它创建了一套全新的局部变量（state、props 都是），而旧的回调函数依然引用着旧的那套变量。

我第一次遇到这个问题是两年前，当时觉得"不就少写了个依赖嘛"，加到数组里就完事了。但实际写代码的时候，尤其是赶工期的时候，真的会忘记这件事。因为代码不报错、不警告，只是表现不对------这种 bug 最阴。

换个场景照样翻车

如果你以为闭包陷阱只在 setInterval 里出现，那就太天真了。只要你的 effect 里创建了一个"长生命周期"的回调------定时器、WebSocket 连接、事件监听器、某些异步链------都有可能中招。上周遇到一个 WebSocket 的例子，问题本质一样：

scss 复制代码

useEffect(() => {
  const ws = new WebSocket(`wss://api.example.com/orders/${orderId}`);
  ws.onmessage = (event) => {
    const order = JSON.parse(event.data);
    // status 永远是建立连接那次的值
    if (order.status !== status) {
      setStatus(order.status);
      playNotification();
    }
  };
  return () => ws.close();
}, [orderId]); // status 没在依赖里

ws.onmessage 回调里读到的 status 永远是建连时的快照。结果是每次状态变更都触发 playNotification()，因为闭包里对比的一直是旧值。测试小哥被铃声响了一下午。

useCallback 也逃不掉

还有一种更隐蔽的变体：你以为用了 useCallback 就安全了，但 useCallback 自己也会踩闭包。

scss 复制代码

function SearchPanel() {
  const [keyword, setKeyword] = useState('');
  const [page, setPage] = useState(1);

  const handleSearch = useCallback(async () => {
    // keyword 和 page 都是闭包捕获的
    const res = await fetch(`/api/search?q=${keyword}&page=${page}`);
    const data = await res.json();
    // ...
  }, []); // 忘了写依赖

  useEffect(() => {
    const timer = setInterval(handleSearch, 5000);
    return () => clearInterval(timer);
  }, [handleSearch]);

  return <input onChange={e => setKeyword(e.target.value)} />;
}

很多人觉得 useCallback 能"固定"函数引用，就不会有闭包问题了。实际上 useCallback 只是让函数引用不变，函数内部读到的 state 依然是创建那次渲染的快照。 handleSearch 被 useCallback 包了一层，依赖数组是空的，所以它永远引用着首次渲染时的 keyword = '' 和 page = 1。不管你调它多少次，请求的参数永远不变。这种情况的修法跟前面一样------要么把依赖写全，要么用 ref 桥接。

ini 复制代码

const handleSearch = useCallback(async () => {
  const res = await fetch(`/api/search?q=${keyword}&page=${page}`);
  // ...
}, [keyword, page]); // ✅ 写全依赖

但这样每次 keyword 变了，handleSearch 引用就变，useEffect 就会重建定时器------对于输入框场景来说，用户每敲一个字母就重建一次定时器，显然不合理。所以这种场景还是得用 useRef 或者 useEffectEvent。

怎么修

几种修法，按场景选。

只是基于上一个值计算新值------用函数式更新

scss 复制代码

useEffect(() => {
  const timer = setInterval(() => {
    setRetryCount(c => c + 1);
  }, 10000);
  return () => clearInterval(timer);
}, []);

setRetryCount(c => c + 1) 里的 c 是 React 传进来的最新 state，和闭包捕获的那个 retryCount 无关。这是最简单的解法，能用就优先用。但问题是我那个仪表盘例子里，setInterval 回调中不仅要 setRetryCount，还要读 retryCount 来拼 toast 文字。函数式更新只能解决"写"的问题，解决不了"读"的问题。

需要在回调中读最新 state------用 useRef 桥接

ini 复制代码

function DataDashboard() {
  const [retryCount, setRetryCount] = useState(0);
  const latestRetryCount = useRef(retryCount);

  useEffect(() => {
    latestRetryCount.current = retryCount;
  }, [retryCount]);

  useEffect(() => {
    const timer = setInterval(async () => {
      const res = await fetch('/api/dashboard');
      if (res.status === 500) {
        const count = latestRetryCount.current + 1;
        showToast(`服务器异常，正在重试（第${count}次）`);
        setRetryCount(count);
      } else {
        const json = await res.json();
        setData(json);
        setRetryCount(0);
      }
    }, 10000);
    return () => clearInterval(timer);
  }, []);

  return <div>...</div>;
}

useRef 的 .current 是引用访问，任何时候读到的都是最新值。代价是多了一个 ref 和同步 effect，代码丑了点，但至少是对的。说实话每次写这段同步代码我都觉得很烦------明明就是一个"在回调里读最新值"的需求，非得绕一圈。

React 19.2+ 的新选择------useEffectEvent

如果你已经在用 React 19.2（当前最新是 19.2.7），有个更舒服的解法。React 19.2 引入了 useEffectEvent，专门解决"effect 里想读最新 state 但不想加依赖"的场景：

scss 复制代码

import { useEffectEvent, useEffect, useState } from 'react';

function DataDashboard() {
  const [retryCount, setRetryCount] = useState(0);

  const handleRefresh = useEffectEvent(async () => {
    // 这里能读到最新的 retryCount
    const res = await fetch('/api/dashboard');
    if (res.status === 500) {
      showToast(`服务器异常，正在重试（第${retryCount + 1}次）`);
      setRetryCount(retryCount + 1);
    } else {
      const json = await res.json();
      setData(json);
      setRetryCount(0);
    }
  });

  useEffect(() => {
    const timer = setInterval(handleRefresh, 10000);
    return () => clearInterval(timer);
  }, [handleRefresh]); // handleRefresh 引用是稳定的

  return <div>...</div>;
}

useEffectEvent 创建的回调引用是稳定的，但它内部能读到最新的 state 和 props。语义比 useRef 桥接清晰很多------你不用手动维护 ref 再同步了。这个 API 我等了挺久的。之前用 useRef 桥接虽然能解决问题，但每次写那段同步代码都觉得是在用战术上的勤奋掩盖战略上的懒惰。useEffectEvent 从根源上把这个心智负担干掉了。

React Compiler 也救不了你

React Compiler（2025 年 10 月发布 1.0）能自动帮你处理 useMemo、useCallback、memo 这些 memoization，减少不必要的重渲染。但它不解决闭包陷阱。原因很简单：闭包陷阱的本质是 effect 中创建了一个长生命周期的回调，回调捕获了渲染时的 state 快照。这是 JavaScript 语言层面的闭包行为，不是 React 的 memoization 问题。Compiler 再怎么优化也改不了 JS 的闭包语义。所以不要指望升了 Compiler 就可以闭着眼睛写 useEffect 了。该写的依赖还是得写，该用 useRef 的地方还是得用。

为什么这个坑这么难防

写了好几年 React，我发现闭包陷阱之所以反复踩，不是因为这个概念有多难理解，而是因为它太"安静"了。不像 TypeScript 类型错误、语法错误那样编译器直接拦住你，闭包陷阱不会报错------代码跑得好好的，只是行为不对。计数器停在 1 不动、通知铃声响个不停、搜索请求永远用同一个关键词，你甚至不确定这是 bug 还是需求理解有误。

而且这个坑有一个很恶心的特性：在开发环境里经常看不出来。因为你调试的时候频繁切页面、改代码、Hot Reload，组件频繁挂载卸载，恰好掩盖了闭包快照的问题。只有上线之后用户正常使用------组件挂着不动、定时器持续跑------问题才暴露。

这也是为什么我那个 bug 能卡两天。本地跑的时候一切正常------开发时我频繁切页面、改代码、Hot Reload 各种折腾，组件动不动就重新挂载，恰好掩盖了闭包快照的问题。只有上线之后用户正常使用，组件挂着不动、定时器持续跑，问题才暴露出来。

测试小哥第一天下午提了 bug，我第二天上午才定位到根因。中间那段时间我其实一直在查后端日志和 Network 面板，完全没想过前端闭包能出这种问题。方向跑偏了，自然查不出结果。

我现在给自己立了个规矩：每次写 useEffect 的时候，如果里面用到了 state 或者 props，就强制自己过一遍检查------ 这个回调的生命周期比当前渲染长吗？如果是，它读到的 state 是快照还是最新值？需要最新值的话，用什么方式拿到？多花 10 秒想一下，比上线后被测试打回来强多了。

lint 规则能帮你挡住大部分低级问题，但覆盖不到的地方还是得靠自己。像我那个 WebSocket 的例子，ws.onmessage 的回调不是 effect 的直接依赖，lint 一般不会报这种。所以该学的原理还是得学，工具终归是辅助。