useEffect依赖数组漏写会有什么后果？怎么用ESLint拦住？

一、依赖数组的作用与“漏写”的运作本质

在深入讨论后果之前，必须建立关于 React 渲染周期的精准心智模型：每一次渲染都有其独立的 Props、State 以及独立的事件处理与 Effect 回调函数。函数组件在重新渲染时，并非在原地“修改”某个已有的变量，而是重新执行整个函数体，创建包含最新变量快照的新作用域。

useEffect 接收的第一个参数是一个函数，该函数在定义时刻，会通过 JavaScript 词法作用域捕获当次渲染中的所有外部变量。如果传给 useEffect 的依赖项不诚实，React 将无法知晓当这些外部变量发生变化时需要销毁旧副作用并重新执行新回调，从而使 Effect 永远被困在过去的闭包之中。

在实际编码中，“漏写依赖”主要表现为以下三种典型形式：

• 形式一：完全缺省依赖数组 useEffect(callback)。不传第二个参数意味着告诉 React“不需要任何跳过判定”，该副作用将在组件初次渲染以及之后的每一次重新渲染后无条件运行。
• 形式二：空依赖数组 useEffect(callback, []) 硬传。内部明确读取了外部的响应式变量（如 props.userId 或 count），却向 React 承诺“该副作用不需要随任何数据变化而重新同步”，导致只在初次挂载时执行一次。
• 形式三：部分漏写派生状态或引用型依赖。仅声明了基本类型的变量，却漏写了副作用内部调用的普通函数、外部对象或从 Context 读取的参数。由于闭包捕获了函数或对象的旧引用，引发间接脱节。

二、依赖数组漏写带来的四大严重后果

很多开发者在遇到警告或死循环时，第一反应往往是随手从依赖数组中移除变量，这种做法只是掩盖了表象，却在运行时埋下了数个难以察觉的系统级缺陷。

1. 闭包旧值陷阱（Stale Closures）导致状态死锁

这是最普遍也最令人头疼的后果。当 useEffect 内部读取了状态，却在依赖数组中漏写或传入 [] 时，该回调函数永远锁定了组件挂载那一帧（Render #1）的数据。

观察下面这个经典的定时器组件案例：

function TimerCounter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => {
      // 这里的 count 永远是挂载时捕获的 0
      console.log("Current count in closure:", count);
      setCount(count + 1);
    }, 1000);

    return () => clearInterval(timer);
  }, []); // ⚠️ 漏写了 count 依赖

  return <div>当前计数：{count}</div>;
}

直觉上，开发者期望屏幕上的数字每秒加 1（0 -> 1 -> 2 -> 3...）。但在实际运行中，数字从 0 变成 1 之后便彻底停滞。原因在于：依赖数组为 []，useEffect 只在挂载时运行一次；定时器回调函数内部闭包持有的 count 变量永远是初始的 0。每过一秒，定时器都在重复执行 setCount(0 + 1)，计算结果始终为 1，导致状态永远无法继续累加。

2. 无限重新渲染死循环（Infinite Re-render Loop）

如果完全省略依赖数组，或者在依赖数组中引用了每次渲染都会生成新内存地址的对象/函数，并在 Effect 内部触发了 setState，将引发浏览器崩溃级别的灾难：

function UserProfile({ userId }) {
  const [userData, setUserData] = useState(null);

  // ⚠️ 完全省略依赖数组
  useEffect(() => {
    fetchUserData(userId).then(data => {
      setUserData(data); // 触发重新渲染 -> 重新渲染再次执行 Effect -> 再次 setState
    });
  });

  return <div>{userData?.name}</div>;
}

执行流程形成闭环：组件渲染 -> 执行 Effect 发起请求 -> 请求回调执行 setUserData -> 组件状态变更触发重新渲染 -> 新渲染再次无条件执行 Effect。若未做节流，浏览器网络面板将瞬间堆满数千条请求，CPU 占用率飙升至 100%，直至 React 抛出 Maximum update depth exceeded 错误。

3. 异步竞态异常与脏数据覆盖（Race Conditions）

在数据搜索、用户详情切换、Tab 标签切换等高频交互场景中，若漏写关联入参（如 query 或 activeTab），副作用不仅不会在参数改变时及时同步数据，更严重的是在网络延迟不均时引发脏数据回写。

即使用户已经从“Tab A”快速切换到了“Tab B”，由于没有正确的依赖清理机制，先发出的 Tab A 慢速响应在几秒后返回，将 Tab B 页面上的数据强行覆盖为 Tab A 的过时内容。用户看到的界面与选中的 Tab 完全脱节。

4. 偶发性生产环境幽灵缺陷

在本地开发环境中，测试数据往往较少，异步接口返回极快，闭包旧值问题可能被偶尔的页面刷新掩盖。但在生产复杂并发环境下，或在 React 18+ 开启并发特性与严格模式（StrictMode 双重挂载/卸载以检验副作用幂等性）时，漏写依赖将直接导致组件在页面切回或重新激活时展现不可预测的空白或断崖式崩溃，且由于堆栈追踪通常指向被动触发的渲染帧，排查成本极高。

三、常见认知误区辨析：为什么很多开发者会“主动漏写”？

在实际代码评审中，很少有人是因为粗心完全忘记传参，更多时候是开发者为了达成某种业务目的而“故意”删掉依赖项。深入辨析这些看似合理的想法，才能真正树立正确的 Hooks 编程范式。

四、怎么用 ESLint 在工程化中彻底拦住漏写？

人工代码审查难以完全杜绝依赖遗漏，依靠静态代码分析工具是前端工程化中最可靠的防线。React 团队官方维护了 eslint-plugin-react-hooks，其中的核心规则就是 react-hooks/exhaustive-deps。

步骤 1：安装官方插件

在项目根目录下，通过包管理器安装开发依赖：

# 使用 npm
npm install --save-dev eslint-plugin-react-hooks

# 或使用 pnpm
pnpm add -D eslint-plugin-react-hooks

# 或使用 yarn
yarn add -D eslint-plugin-react-hooks

提示：如果使用的是现代脚手架（如 Vite 的 React 模板、Next.js 或 Create React App），该插件通常已经被预装并内置于基础配置中。

步骤 2：在 ESLint 中配置拦截规则

根据项目采用的 ESLint 配置规范版本，选择对应配置方式：

A. 传统配置方式（.eslintrc.js / .eslintrc.json）

module.exports = {
  // ... 其他配置
  plugins: [
    'react-hooks'
  ],
  rules: {
    // 检查 Hooks 使用规则（不可在条件分支/循环中调用）
    'react-hooks/rules-of-hooks': 'error',
    // 检查 Effect 依赖项完整性：建议在团队中设置为 error 级别
    'react-hooks/exhaustive-deps': 'error'
  }
};

B. 现代扁平配置方式（ESLint 9+ eslint.config.js）

import reactHooks from 'eslint-plugin-react-hooks';

export default [
  {
    plugins: {
      'react-hooks': reactHooks,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      // 强校验：一旦遗漏直接阻断编译
      'react-hooks/exhaustive-deps': 'error',
    },
  },
];

步骤 3：编辑器实时反馈与终端报错信息解读

当开发人员在 VSCode 或 WebStorm 中漏写依赖时，ESLint 语言服务器会立即在 useEffect 的依赖数组位置绘制波浪线，并在光标悬浮时输出官方的精确诊断信息：

ESLint Error:
React Hook useEffect has a missing dependency: 'count'. 
Either include it or remove the dependency array. (react-hooks/exhaustive-deps)

在运行 npm run lint 或执行 CI/CD 流水线时，该规则将直接使构建失败，彻底阻断存在闭包陷阱的代码合入主干分支。

五、被 ESLint 拦截后，如何安全规范地修复？（五大实战策略）

当 ESLint 提示缺少依赖时，很多新手的做法是直接按照提示把所有标红的变量一股脑丢进 [...]，结果页面立刻死循环，随后转手加上 eslint-disable 注释。这是一种极其不健康的恶性循环。

正确的应对方式是依据具体的逻辑意图，选择以下五种标准治理模式之一：

策略一：改用“函数式更新”（消除对旧 State 的显式依赖）

适用场景：在副作用中调用 setState，且新值仅由旧状态推导而来（如计数累加、布尔值取反、列表追加）。

// ❌ 错误做法：直接读取 count，被迫加入依赖导致定时器频繁重建
useEffect(() => {
  const id = setInterval(() => {
    setCount(count + 1);
  }, 1000);
  return () => clearInterval(id);
}, [count]);

// ✅ 优雅方案：函数式更新，Effect 不再需要读取外部 count，依赖数组安全留空
useEffect(() => {
  const id = setInterval(() => {
    setCount(prev => prev + 1);
  }, 1000);
  return () => clearInterval(id);
}, []); // 符合规则，且定时器平稳运行不重复销毁

策略二：将辅助函数内移至 useEffect 内部

适用场景：该函数仅仅服务于当前的 useEffect，不被组件其他地方调用。

// ❌ 容易引发死循环的做法：在组件体内定义函数
function UserProfile({ userId }) {
  const fetchUser = () => {
    api.getUser(userId);
  };

  useEffect(() => {
    fetchUser();
  }, [fetchUser]); // fetchUser 每次 render 都是新引用，无限重新触发！
}

// ✅ 推荐方案：将 fetchUser 移入 Effect 作用域内部
function UserProfile({ userId }) {
  useEffect(() => {
    const fetchUser = () => {
      api.getUser(userId);
    };

    fetchUser();
  }, [userId]); // 依赖纯净收敛为基元类型 userId，清晰受控
}

策略三：将无依赖的纯函数抽离到组件外部

适用场景：辅助处理函数（如数据格式化、校验算法、计算逻辑）不读取组件内的任何 props 或 state。

// ✅ 将不依赖响应式状态的函数置于组件外部
function formatData(raw) {
  return raw.trim().toLowerCase();
}

function SearchBox({ keyword }) {
  useEffect(() => {
    const query = formatData(keyword);
    performSearch(query);
  }, [keyword]); // formatData 在外部具有静态内存地址，不需要放进依赖
}

策略四：使用 useCallback 或 useMemo 固化引用

适用场景：函数或对象需要同时被组件 JSX 中的事件监听器（如按钮点击）以及 useEffect 共同调用。

function ProductList({ categoryId }) {
  // 使用 useCallback 锁死函数引用，仅在 categoryId 变更时生成新函数
  const reloadData = useCallback(() => {
    api.fetchCategory(categoryId);
  }, [categoryId]);

  useEffect(() => {
    reloadData();
  }, [reloadData]); // 诚实声明依赖，且 reloadData 引用稳定，绝不会死循环

  return <button onClick={reloadData}>手动刷新</button>;
}

策略五：使用 useRef 托管“仅需最新值而不需触发副作用”的变量

适用场景：副作用只需要在触发时读取某个变量的“最新快照”，但该变量本身的改变不应该成为触发副作用重新执行的条件。

function ChatRoom({ roomId, theme }) {
  // 期望：仅在 roomId 变化时重新连接聊天室；连接成功时读取 theme 打日志
  const themeRef = useRef(theme);
  
  // 每次渲染同步更新 ref.current
  useEffect(() => {
    themeRef.current = theme;
  });

  useEffect(() => {
    const conn = connect(roomId);
    conn.on('connected', () => {
      console.log('Connected with theme:', themeRef.current);
    });
    return () => conn.disconnect();
  }, [roomId]); // theme 不需要放入依赖，不会因为主题切换导致聊天室断开重连！
}

六、总结与团队工程化落地建议

要彻底终结 useEffect 带来的各种偶发缺陷，关键在于转变心智模型：不要试图把 useEffect 当作类组件的生命周期钩子（didMount / didUpdate）来使用，而要将其视为“将组件外部系统与当前状态保持同步的声明式通道”。

针对团队协作，建议制定以下三条硬性规范：

1. 升级规则为强制错误（Error）：在 ESLint 中将 react-hooks/exhaustive-deps 设置为 "error" 而不是 "warn"，警告极易在日常开发中被忽略并积重难返。
2. 建立预提交拦截（Pre-commit Hooks）：利用 husky 与 lint-staged 在本地 Git 提交时自动执行代码检查，确保存在依赖漏写的代码无法生成提交记录。
3. 将 disable 注释纳入 Code Review 重点排查项：在代码库中搜索 eslint-disable-next-line react-hooks/exhaustive-deps，任何新增的禁用注释必须在评审中附带详尽的理由与架构解释，否则严禁合入。

保持依赖数组的诚实与完整，不仅能够保护代码免受闭包陷阱与死循环的侵扰，更能使代码在未来的 React 新版本中无缝兼容并发渲染与自动化优化。