快速上手 stop-runaway-react-effects：npm 一条命令搞定 React Effect 死循环监控

stop-runaway-react-effects 是一款专为 React 开发者打造的 Effect 死循环监控工具：它在开发阶段自动拦截 useEffect / useLayoutEffect 被高频重复调用的"失控 effect"，把完整诊断信息打印到控制台，并直接抛出错误中断死循环——一条 npm install 命令即可让这类隐蔽 bug 无所遁形。

🐛 为什么 React 里会出现 Effect 死循环？

用过 React Hooks 的同学大概率都踩过这个坑：

1. useEffect 的回调里修改了状态（set state）；
2. 状态变化触发重新渲染；
3. 依赖数组里的某个值"变了"（比如渲染中创建的对象、数组）；
4. React 再次执行 effect → 又改状态 → 再渲染 → 无限循环 🔄

后果可能很严重：浏览器卡到转圈、疯狂请求接口触发限流（rate-limited）、开发机风扇狂转。手动排查这种问题非常痛苦，因为你甚至不知道循环发生在哪个 effect 上。

🔍 它是怎么监控 Effect 调用频率的？

stop-runaway-react-effects 的核心思路很简单：包装（hijack）React 的 effect hooks，给每次调用"打卡"。

核心实现位于 src/index.js，它会把 React.useEffect 和 React.useLayoutEffect 替换成带监控的版本：

• 📊 记录每次回调调用的时间戳和依赖数组；
• ⏱️ 默认阈值：callCount: 60、timeLimit: 1000（即 1 秒内调用 60 次就判定为失控，见 src/index.js）；
• 🚨 触发阈值后做三件事：
  1. 在控制台打印 effect 回调的源代码；
  2. 打印最近 60 次调用各自的依赖数组，并标出每次之间哪些依赖变了（未变化的会显示 UNCHANGED）；
  3. 抛出 Error，直接掐断死循环，避免浏览器被拖垮。

而且它在报错时非常"贴心"：如果你的 effect 根本没传依赖数组，它会建议你补上 []；如果检测到某个依赖每次都在变，它会明确提示你"大概率需要用 React.useMemo 或 React.useCallback 做记忆化"。

🚀 一条命令安装，两步完成接入

第一步：一键安装

npm install --save stop-runaway-react-effects

💡 要求 react >= 16.8.x（Hooks 支持的版本），依赖声明见 package.json。

第二步：在应用入口启用监控

方式一：显式调用（适合放在独立的 bootstrap 文件里）

// src/bootstrap.js
import {hijackEffects} from 'stop-runaway-react-effects'

if (process.env.NODE_ENV === 'development') {
  hijackEffects()
}

然后在入口文件里先 import './bootstrap' 再导入 React，保证 effect 在被引入前就已被包装。

方式二：一行 import（更省事，推荐）

// src/index.js
import 'stop-runaway-react-effects/hijack'
import React, {useEffect} from 'react'

这个 hijack 子模块的实现只有几行（见 hijack.js）：仅当 NODE_ENV === 'development' 时才生效，生产环境完全不打扰。

🎯 捕获效果演示：控制台直接告诉你"谁在裸奔"

先看一种典型情况——useEffect 完全没有传依赖数组，每次渲染都会执行回调。接入监控后，控制台会输出这样的诊断：

可以看到：顶部黄色警告列出了回调源码和"请补上依赖数组"的修复建议；红色错误则直接中断了循环，并顺带告诉你"这个报错来自 stop-runaway-react-effects，不是 React 本身"。

再看另一种更隐蔽的情况——依赖数组里有一个每次渲染都重新创建的对象。此时 effect 每次都"合法"地重新运行，问题肉眼几乎无法察觉：

控制台会逐次对比依赖变化，把每个未变化的项标记为 UNCHANGED，变化的项高亮显示——一眼就能锁定那个"每次都在变"的对象，然后去它的初始化位置加上 useMemo 即可。

⚙️ 如何定制 callCount 与 timeLimit 参数

默认阈值可以通过 options 调整，完整的 TypeScript 类型定义见 typings/index.d.ts：

// 自定义阈值：2 秒内调用 120 次才告警
hijackEffects({callCount: 120, timeLimit: 2000})

如果只想监控某一个 hook（比如只盯着 useLayoutEffect），可以用 hijackEffectHook：

import {hijackEffectHook} from 'stop-runaway-react-effects'

hijackEffectHook('useLayoutEffect', {callCount: 60, timeLimit: 1000})

另外，hijackEffects() 的返回值是一个 restore 函数，调用它即可恢复 React 原始的 hook——这在单元测试中很有用。

🛡️ 生产环境零开销，放心使用

这是一个仅开发阶段生效的工具，对生产构建没有任何影响：

• 生产模式下 hijackEffects / hijackEffectHook 会自动退化为空函数（noop，见 src/index.js），即使误调用也安全无副作用；
• 使用现代打包工具（webpack、parcel、rollup）配合 NODE_ENV 优化后，相关代码会被整体 tree-shake 掉；
• 项目内置了专门验证生产行为的测试：src/tests/prod.js。

📁 项目文件导航

文件	说明
src/index.js	核心实现：hook 包装、调用频率检测、依赖对比与抛错
hijack.js	开发环境专属的一行 import 入口
typings/index.d.ts	Options（callCount / timeLimit）等类型定义
src/tests/index.js	功能测试（失控 effect 的各种形态）
README.md	官方文档，含完整使用示例
CHANGELOG.md	版本变更记录

❓ 常见问题 FAQ

Q：会不会误伤正常的 effect？ A：只有"短时间内调用次数超过阈值"才会触发（默认 1 秒 60 次）。如果你的业务确实需要高频 effect，调大 callCount 或 timeLimit 即可。

Q：和 eslint-plugin-react-hooks 是什么关系？ A：互补。ESLint 插件是静态检查依赖数组写法，stop-runaway-react-effects 是运行时监控实际调用频率，官方也建议在触发"无依赖"警告时配合安装该 ESLint 插件。

Q：能用来跑单元测试吗？ A：可以。它导出的是纯函数，测试代码 src/tests/index.js 就是搭配 @testing-library/react 在 Jest 里直接验证告警文案的，你完全可以在自己的测试中复用同一套写法。

✅ 小结

特性	说明
解决的问题	use(Layout)Effect 高频重入导致的死循环
生效环境	仅开发阶段，生产零开销
默认阈值	1000ms 内 60 次调用
触发后行为	控制台输出完整诊断 + 抛错中断
安装成本	一条 npm 命令 + 一行 import

当你再遇到"浏览器莫名卡死、请求被限流"却找不到原因时，把 stop-runaway-react-effects 挂到开发环境里，控制台会直接指认那个失控的 effect，并告诉你该怎么修。🏃