ESLint的react-hooks规则怎么配？能拦住哪些错误？

一、如何配置 react-hooks 规则

配置过程主要分为三个核心动作：在项目中安装插件依赖、按项目所用的 ESLint 架构载入配置预设、在开发工具与命令行中完成执行验证。

1. 安装开发依赖

在项目根目录下通过包管理器将 eslint-plugin-react-hooks 写入 devDependencies。该插件作为开发期静态分析工具，不需要打包到生产运行时产物中：

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

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

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

2. 方案 A：新版 Flat Config（ESLint v9+）配置

如果项目使用的是 ESLint 9 及以上版本，配置文件采用扁平化配置体系（eslint.config.js 或 eslint.config.mjs）。此时需要直接导入插件对象并将其注入到配置数组中：

// eslint.config.js
import js from '@eslint/js';
import reactHooks from 'eslint-plugin-react-hooks';

export default [
  js.configs.recommended,
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      'react-hooks': reactHooks,
    },
    rules: {
      // 展开官方推荐规则集（包含 rules-of-hooks 与 exhaustive-deps）
      ...reactHooks.configs.recommended.rules,
      
      // 也可在此处显式自定义规则严重程度
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
    },
  },
];

3. 方案 B：传统 Legacy 格式（ESLint v8 及更早）配置

在 Vite、Create React App 或旧有脚手架项目中，如果仍使用 .eslintrc.js、.eslintrc.cjs 或 .eslintrc.json，推荐直接通过 extends 继承官方集成的推荐预设：

// .eslintrc.cjs
module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended', // 继承 react-hooks 官方推荐配置
  ],
  rules: {
    // 默认已开启：
    // 'react-hooks/rules-of-hooks': 'error',
    // 'react-hooks/exhaustive-deps': 'warn',
  },
};

4. 高级配置：自定义 Hook 依赖项检查

团队如果自行封装了具有类似 useEffect 依赖行为的自定义 Hook（如 useUpdateEffect、useDeepCompareEffect），默认情况下 ESLint 并不会对自定义名称做依赖检查。可以通过为 exhaustive-deps 传递 additionalHooks 正则参数将其纳入防护网：

// 自定义 Hook 依赖检查正则配置
rules: {
  'react-hooks/exhaustive-deps': [
    'warn',
    {
      additionalHooks: '(useCustomEffect|useUpdateEffect)',
    },
  ],
}

二、规则一：rules-of-hooks 能拦住哪些错误？

react-hooks/rules-of-hooks 是一条不可退让的硬性规则，官方建议其严重级别始终设置为 'error'。它用于确保开发者遵循 React Hooks 的两条核心调用铁律：只在 React 函数组件或自定义 Hook 的最顶层调用 Hook，绝不在循环、条件或嵌套函数中调用 Hook。

1. 为什么不能在条件分支或循环中调用 Hook？

React 底层的 Fiber 架构中，并没有通过键名（Key）来记录各个 useState 或 useEffect 的状态，而是为每个组件实例维护了一条单向链表（Linked List）。在组件初次渲染（Mount）时，React 按照代码从上往下的执行顺序，依次创建 Hook 节点并挂载到链表上；在后续更新（Update）时，React 依据完全相同的执行次序，使用内部游标依次向后移动读取旧节点状态。

如果在条件分支中调用 Hook，一旦条件状态发生改变，导致某个 Hook 被跳过，后续所有 Hook 的调用次序将与 Fiber 链表槽位产生错位，变量读取到的是前一个 Hook 遗留的状态值，直接造成应用逻辑雪崩。

2. 典型拦截错误一：if 条件判断中调用 Hook

下面的代码根据传入的 isVip 属性动态创建了一个状态，这在 React 中是极其危险的：

function UserProfile({ isVip }) {
  const [name, setName] = useState('Alice');

  // 错误：在条件分支内调用 Hook！
  if (isVip) {
    const [discount, setDiscount] = useState(0.8);
  }

  const [age, setAge] = useState(25);
  // ...
}

ESLint 拦截报错：

ESLint: React Hook "useState" is called conditionally. 
React Hooks must be called in the exact same order in every component render. (react-hooks/rules-of-hooks)

后果排查：当用户从非 VIP 变为 VIP 时，组件在 Update 阶段多执行了一次 Hook 调用，React 发现本轮渲染的 Hook 总数与上一轮不符，会在控制台直接抛出不可恢复的运行时崩溃：Rendered more hooks than during the previous render。

3. 典型拦截错误二：在提前返回（early return）之后调用 Hook

开发者常习惯在接口加载中写 if (loading) return <Spinner />;。如果在提前退出语句之后又调用了 Hook，本质上同样构成了条件调用：

function DataViewer({ loading, data }) {
  const [filter, setFilter] = useState('');

  if (loading) {
    return <div>加载中...</div>; // 提前返回导致后续 Hook 被跳过
  }

  // 错误：在提前 return 之后调用 Hook！
  useEffect(() => {
    console.log('数据载入完成', data);
  }, [data]);

  return <div>{data.title}</div>;
}

正确修复：所有 Hook 的调用必须置于任何 return 语句之前，副作用内部逻辑如有前置条件，应当在 useEffect 的回调函数体内部编写 if (loading) return;。

4. 典型拦截错误三：在事件回调或普通辅助函数中调用 Hook

function ActionButton() {
  function handleClick() {
    // 错误：在事件处理函数内部调用 Hook！
    const [clicked, setClicked] = useState(true);
  }

  return <button onClick={handleClick}>点击</button>;
}

ESLint 拦截报错：提示 React Hook "useState" is called in function "handleClick" which is neither a React function component or a custom React Hook function。Hook 无法脱离组件渲染主上下文独立运行。

三、规则二：exhaustive-deps 能拦住哪些错误？

react-hooks/exhaustive-deps 聚焦于组件的数据流一致性与生命周期安全。它利用静态分析，扫描 useEffect、useLayoutEffect、useCallback 与 useMemo 的函数体，找出所有来自组件作用域的响应式变量（包括 props、state 以及由此派生的局部变量），并核对它们是否都被完整列入依赖项数组（Dependency Array）。

1. 典型拦截错误一：陈旧闭包与脏数据读取（Stale Closures）

JavaScript 的函数闭包在创建时捕获当次执行上下文中的变量。在 React 中，每次渲染都有自己专属的 Props 和 State。如果副作用使用了状态变量，却未在依赖数组中声明，该副作用将永远被困在旧渲染周期的闭包中：

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

  useEffect(() => {
    const timer = setInterval(() => {
      // 错误：闭包捕获了挂载时的 count(0)，后续每秒执行时计算的永远是 0 + 1 = 1！
      setCount(count + 1);
    }, 1000);

    return () => clearInterval(timer);
  }, []); // 缺少 count 依赖

  return <h1>计数：{count}</h1>;
}

ESLint 拦截告警：

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

正确解法（函数式更新）：如果仅需要基于先前的状态值计算下一个状态，无需直接引用 count 变量，改为向 setCount 传入更新函数 setCount(prev => prev + 1)。此时 useEffect 不再读取外部 count，依赖数组保持 [] 成立，定时器无需频繁销毁重建，彻底解决闭包陈旧问题。

2. 典型拦截错误二：因修复依赖而盲目引入“死循环重渲染”

许多开发者在看到 ESLint 告警后，未经分析便将变量直接塞入依赖项，引发了更严重的死循环问题：

function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    // 错误示范：在 effect 内更新 users，同时将 users 设为依赖！
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data));
  }, [users]); // 每次 setUsers 会触发组件重新渲染，重新渲染又执行 effect，造成死循环请求！

  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

exhaustive-deps 的存在正是为了迫使开发者正视这一架构冲突：副作用的触发条件与副作用产生的结果之间存在反馈回路。此处真正的诉求是“仅在挂载时拉取一次”，应该将请求逻辑与 users 解耦，依赖数组保持为空。

3. 典型拦截错误三：对象与函数引用不稳定导致的频繁无效执行

在组件体内定义的普通函数或对象字面量，在每次组件渲染时都会分配全新的内存地址引用。如果这些引用直接作为依赖项，将导致 Effect 在每次渲染后都被无意义地重新触发：

function SearchBox({ onSearch }) {
  const [query, setQuery] = useState('');

  // 每次 SearchBox 渲染，options 都是全新的对象引用！
  const options = { exact: false, timeout: 3000 };

  useEffect(() => {
    onSearch(query, options);
  }, [query, options, onSearch]); // options 导致 effect 每轮都重复执行！

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

排查与优化对策：

• 对策 A（移至组件外）：如果对象或配置不依赖组件内的任何变量，将其移到组件函数声明外部，保持全局引用恒定。
• 对策 B（移至 Effect 内部）：若配置仅供该 Effect 使用，直接在 useEffect 回调函数内部声明 options。
• 对策 C（使用 useMemo/useCallback）：若该对象需跨多个子组件或 Hook 传递，使用 useMemo(() => ({ exact: false, timeout: 3000 }), []) 进行引用固化。

四、规则配置常见误区与避坑指南

1. 严禁滥用 eslint-disable-next-line 注释抑制告警

在开发中经常能见到以下代码：

useEffect(() => {
  fetchDetail(id, userRole);
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, []);

2. 不需要且不应将 ref.current 写入依赖数组

React 官方设计中，useRef 返回的 ref 对象其本身引用在组件整个生命周期中是不可变的，因此将 ref 写入依赖不会有副作用。但是，修改 ref.current 不会触发组件重新渲染。ESLint 插件内部已经做了专门的优化识别，不会强求将 ref.current 放入依赖列表；如果强行写入，不仅无法响应 current 的变动，反而会给其他阅读代码的维护者带来“该 Effect 会在 current 改变时触发”的错误预期。

3. 自定义 Hook 必须保持 use 开头的命名约定

ESLint 插件通过函数命名前缀来识别自定义 Hook。如果自定义 Hook 被命名为 fetchUserData 而不是 useUserData，内部调用 useState 时会被 rules-of-hooks 误判为“在普通辅助函数中违规调用 Hook”而抛错，同时也无法享受 exhaustive-deps 的自动扫描机制。

总结而言，eslint-plugin-react-hooks 并非给开发者带来枷锁的繁文缛节，而是将 React 内部精妙的调度机制透明化、防护前置化的工程利器。通过在项目中配置这两条规则并将其融入本地 IDE、Git Pre-commit 钩子与 CI/CD 门禁流水线，团队可以在编码阶段彻底消灭大多数隐蔽的运行时 Bug，构建出高健壮性、可预测的现代 React 应用程序。