自定义Hook为什么必须以use开头？

一、直观现象：如果不用 use 开头会发生什么？

初学 React 自定义 Hook 时，不少开发者会有这样的疑问：“既然自定义 Hook 就是普通函数里调用了 useState 或 useEffect，为什么我给它起名叫 fetchUserProfile 或 calculateWindowSize 就不行，非要叫 useUserProfile 或 useWindowSize？”

要观察这个约束的作用，最直接的办法就是故意破坏命名规范，写一个在普通函数里调用 Hook 的例子：

// 错误示范：没有遵循 use* 命名的自定义函数
import { useState, useEffect } from 'react';

function getUserProfile(userId) {
  // ESLint 会在此处给出红色下划线警告
  const [user, setUser] = useState(null);

  useEffect(() => {
    api.fetchUser(userId).then(setUser);
  }, [userId]);

  return user;
}

当项目配置了标准 React ESLint 规则集时，上述代码会立即在 useState 所在行触发一条明确的语法校验报错：

这条报错直截了当地告诉我们：静态检查工具只认两类可以调用 Hook 的函数——首字母大写的 React 组件函数（如 UserProfile），以及以小写 use 紧跟大写字母开头的自定义 Hook 函数（如 useUserProfile）。对于 getUserProfile 这样的普通驼峰命名，检查工具将其判定为“普通通用工具函数”，因而判定在其中调用 Hook 属于违法操作。

二、静态分析协议：ESLint 如何依据命名判定函数性质

React 官方之所以把这个规则建立在“命名”而非“元数据”或“装饰器”上，是因为 JavaScript 是一门动态语言。在不引入复杂的重型编译方案前提下，代码静态分析插件需要一种低成本、无歧义且跨编辑器通用的方式，来区分哪些函数需要接受严格的 Hook 规则制约。

React ESLint 插件内部使用抽象语法树（AST）扫描函数声明。其核心匹配逻辑正是正则规则 /^use[A-Z0-9]/。只要函数标识符命中该模式，插件就会自动为该函数激活两条铁律：

1. 内部校验：该函数内部允许调用其他 Hook，但这些子 Hook 必须出现在顶层，严禁被 if、for 或嵌套回调包裹；
2. 依赖完整性校验：自动分析函数内部对 props 或 state 的引用，强制 useEffect、useMemo 等补全依赖项；
3. 外部传递校验：其他人在调用该函数时，必须将其视为 Hook 对待，不能将其放入条件分支或事件处理函数内部。

如果缺少了 use 前缀，整个安全防线就会瞬间瓦解。设想一下：如果检查器允许你在名为 getDistance 的普通函数里任意写 Hook，那么其他开发者在业务代码中看到 getDistance 时，很可能会毫不犹豫地在 onClick 点击事件回调或 if (isActive) 条件语句中调用它。而一旦在条件语句或事件回调中触发 Hook，就将直接引发 React 运行时的严重灾难。

三、运行时底层真相：React Fiber 链表的“顺序依赖”

为什么不能在条件判断或循环中调用 Hook？这必须深入到 React 的底层数据结构中。

在 React Fiber 架构中，每个函数组件在内存中都对应一个 FiberNode 节点。令人意外的是，React 并没有在 Fiber 节点上为每个 Hook 维护一个基于“变量名”的哈希映射表（比如并没有 fiber.hooks["user"] = ... 这样的键值对）。相反，所有的 Hook 状态都以单向链表的形式串联在 fiber.memoizedState 上。

每个 Hook 节点包含当前状态值 memoizedState、更新队列 queue 以及指向下一个 Hook 的指针 next。当组件执行二次渲染时，React 内部仅维护一个全局游标（workInProgressHook 指针）。

在二次渲染过程中，React 每执行一次 Hook 函数调用，游标就沿着单向链表向后移动一位（next）。这意味着：

• 第 1 次调用的 Hook 必定获取链表中的第 1 个节点数据；
• 第 2 次调用的 Hook 必定获取链表中的第 2 个节点数据；
• 自定义 Hook 内部的所有 Hook，其节点在链表中是**扁平展开**的，直接依次插在宿主组件的链表序列里。

如果某个自定义 Hook 没有被 use 规范约束，导致外部调用者将其包在 if (isVip) 条件分支中执行，那么一旦 isVip 从 true 变成 false，链表中的对应节点就会被跳过。此时，后续所有的 Hook 游标全部前移一位，导致本属于状态 B 的值被错误读入状态 A，最终触发著名的运行时白屏错误：Rendered fewer hooks than expected。

四、职责边界：普通工具函数、自定义 Hook 与组件对比

理解了命名机制和链表原理后，我们就能清晰界定前端代码组织中的三种常见函数类型。很多开发者在重构业务逻辑时，往往犹豫是将逻辑抽离为普通工具类（Util），还是封装为自定义 Hook。

下表及图示展示了普通工具函数、以 use 命名的自定义 Hook、以及以大写字母开头的函数组件之间的权限差异与职责分工：

从中可以看出关键的区别点：

• 普通函数（util）：没有状态持久化需求，单纯执行输入到输出的计算，可以在任何位置被自由调用，因此严禁加 use 前缀，否则会给调用者带来不必要的顶层调用负担；
• 自定义 Hook（useXxx）：逻辑需要读取或改变 React 状态、注册生命周期副作用或订阅上下文，必须严格加上 use 前缀，从而主动通知静态分析器为其开启防护网；
• 函数组件（Component）：负责产出 JSX 并映射到真实 DOM 结构，首字母大写以区别于原生 HTML 标签。

五、工程落地指南：编写自定义 Hook 的标准化决策

在实际项目研发中，掌握自定义 Hook 的正确封装步骤，能够有效避免逻辑污染与规则失效。我们可以通过一个标准的四步工作流来完成抽取：

1. 识别状态与副作用依赖

审视待抽取的业务逻辑代码。如果该逻辑只依赖纯参数运算（例如格式化时间戳、深拷贝对象、数学公式计算），直接封装为纯函数，放在 utils/ 目录下，绝对不要以 use 开头；如果该逻辑需要监听窗口尺寸（依赖 window.addEventListener）、订阅全局数据流或管理局部 loading 状态，则判定需要封装为自定义 Hook。

2. 规范命名与导出结构

自定义 Hook 必须且只能命名为 use 加上大驼峰词组，例如 useWindowDimensions 或 useDebouncedValue。

// 正确示范：标准自定义 Hook
import { useState, useEffect } from 'react';

export function useWindowDimensions() {
  const [dimensions, setDimensions] = useState({
    width: window.innerWidth,
    height: window.innerHeight,
  });

  useEffect(() => {
    function handleResize() {
      setDimensions({
        width: window.innerWidth,
        height: window.innerHeight,
      });
    }

    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return dimensions;
}

3. 验证 ESLint 工具链协同

在工程中确保配置了 eslint-plugin-react-hooks。当在组件中使用 useWindowDimensions 时，检查工具会自动确保你没有在 if 分支内调用它。

六、总结

回到文章的核心问题：“自定义 Hook 为什么必须以 use 开头？”

答案可以凝练为两句话：在底层，React Fiber 的链表式状态管理决定了 Hook 调用的顺序绝对不能被条件或循环破坏；在工程层，静态分析工具必须依据统一的 use 命名协议来识别 Hook 并建立跨文件的调用约束防线。

以 use 开头不仅是命名风格的约定，更是 React 框架与工程工具链之间达成的“安全契约”。正是有了这份契约，复杂的业务状态和副作用才得以在组件间安全、优雅地复用。