• 人工智能
• 大模型
• AI 应用
• 前端
• 后端

本篇技术指南围绕 Vercel 工程团队发布的 React 性能最佳实践规则集（仓库内位于.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md）中的Narrow Effect Dependencies（收窄 Effect 依赖）规则展开，并结合 BibiGPT-v1 这一 Next.js/React 音视频 AI 总结应用的真实源码进行印证。读完本文，你将掌握：为什么 useEffect 依赖数组里应写原始类型而不是对象、如何把"派生状态"移出 Effect 以消除连续数值导致的重复执行，以及一套可立即用于代码审查与重构的检查清单。

规则速览：影响等级与定位

在 Vercel React Best Practices 的八类规则中，rerender-dependencies属于第 5 类Re-render Optimization（重渲染优化），标记为impact: LOW，impactDescription: minimizes effect re-runs（最小化 Effect 的重复执行）。其核心主张只有一句话：

Specify primitive dependencies instead of objects to minimize effect re-runs. （在 Effect 依赖数组中指定原始类型依赖，而不是对象，以最小化 Effect 的重复执行。）

规则的 frontmatter 元数据（rerender-dependencies.md）如下：

title: Narrow Effect Dependencies impact: LOW impactDescription: minimizes effect re-runs tags: rerender, useEffect, dependencies, optimization

虽然单项影响评级为 LOW，但它与rerender-derived-state（订阅派生布尔状态）、rerender-derived-state-no-effect（渲染期派生而非 Effect 更新）等规则配合使用时，能显著减少组件重渲染频率，属于"高频小收益、积少成多"的优化手段。

为什么对象依赖会让 Effect 反复执行

React 对 Effect 依赖数组的比对基于Object.is语义：每次渲染后，React 会逐个比较依赖项与上一次的值是否相同（same value）。问题在于：

• 原始类型（primitive）：数字、字符串、布尔值等按值比较。只要数值没变，Object.is就判定相等。
• 对象/引用类型：user、props、config等按引用比较。只要父组件重新渲染（哪怕只改动了对象里一个无关字段），传入的user对象就是一个全新的引用，Object.is判定不等，Effect 随之重新执行。

因此，当 Effect 内部实际上只读取了对象的某个字段时，把整个对象写进依赖数组就属于"依赖过宽"（over-broad dependencies）——Effect 会被与它无关的字段变更反复触发，造成不必要的副作用执行、多余的 API 请求、日志噪音甚至竞态。

错误写法：依赖整个对象

useEffect(() => { console.log(user.id) }, [user])

只要user的任何字段变化导致新对象产生（例如user.name更新、user.avatar重设），即便user.id完全没变，这个 Effect 也会重新运行。

正确写法：只依赖用到的原始字段

useEffect(() => { console.log(user.id) }, [user.id])

user.id是字符串/数字原始类型，只有它真正改变时 Effect 才会重跑。这正是"依赖收窄"的核心操作：Effect 依赖什么，就精确声明什么；没有用到的数据，不要混进依赖数组。

实践提示：如果 Effect 内同时用到多个字段，可分别列出原始字段，例如[user.id, user.email]；如果 Effect 依赖的是"由多个字段计算出的布尔条件"，则应遵循下一节的派生状态范式。

派生状态：在 Effect 之外计算，而不是依赖连续数值

规则的第二部分给出一个非常典型的实战场景：根据窗口宽度判断移动端模式。直接订阅连续变化的width数值会导致 Effect 在width = 767、766、765...时反复触发。

错误写法：依赖连续数值

// Incorrect: runs on width=767, 766, 765... useEffect(() => { if (width < 768) { enableMobileMode() } }, [width])

这里width是连续变化的数值状态（每次 resize 事件都可能产生新值），Effect 会在 767、766、765……每一个中间值上都执行一次，即便enableMobileMode()的语义只关心"是否小于 768"这一个布尔结论。

正确写法：先派生布尔值，再依赖布尔值

// Correct: runs only on boolean transition const isMobile = width < 768 useEffect(() => { if (isMobile) { enableMobileMode() } }, [isMobile])

先把连续数值width派生为布尔值isMobile（布尔是原始类型），再把它作为依赖。这样 Effect 只会在布尔值发生真/假跳变时执行一次，而不是在每个中间像素值上都执行。

这一步其实把"渲染期派生"（const isMobile = width < 768）和"原始类型依赖"（[isMobile]）两种范式叠加在了一起，是rerender-dependencies与rerender-derived-state（订阅派生布尔状态，而非连续值）规则的结合点。同目录的 rerender-derived-state.md 给出了更彻底的替代方案——用useMediaQuery('(max-width: 767px)')之类的媒体查询 Hook 直接返回布尔值，把"宽度→布尔"的派生逻辑下沉到订阅源头：

function Sidebar() { const isMobile = useMediaQuery('(max-width: 767px)') return <nav className={isMobile ? 'mobile' : 'desktop'} /> }

BibiGPT-v1 仓库中的落地印证

该规则并非纸上谈兵，BibiGPT-v1 的源码里可以找到完全对应的实现。最典型的是 hooks/use-window-size.ts：它监听resize事件并把width/height存入 state，但返回值刻意只暴露派生后的布尔量isMobile、isDesktop，而不是让调用方直接消费连续数值：

useEffect(() => { function handleResize() { setWindowSize({ width: window.innerWidth, height: window.innerHeight, }) } window.addEventListener('resize', handleResize) handleResize() return () => window.removeEventListener('resize', handleResize) }, []) // Empty array ensures that effect is only run on mount return { windowSize, isMobile: typeof windowSize?.width === 'number' && windowSize?.width < 768, isDesktop: typeof windowSize?.width === 'number' && windowSize?.width >= 768, }

可以看出两点：

1. 断点 768 与规则示例一致：width < 768就是移动端判定阈值，与规则中的const isMobile = width < 768完全同构；
2. 派生布尔对外、连续数值收内：组件层拿到的是稳定的isMobile: boolean，不会因为每次 resize 中间值的变化而频繁重渲染。

它的消费方 components/shared/modal.tsx 正是这样使用的——组件只订阅isMobile/isDesktop两个布尔值来决定渲染移动端 Leaflet 还是桌面端模态框：

const { isMobile, isDesktop } = useWindowSize() return ( <AnimatePresence> {showModal && ( <> {isMobile && <Leaflet setShow={setShowModal}>{children}</Leaflet>} {isDesktop && (/* 桌面端 FocusTrap + motion.div 模态框 */)} </> )} </AnimatePresence> )

从源码结构看，这种"布尔派生 + 布尔依赖"的设计正是rerender-dependencies规则的工程化表达：窗口尺寸再怎么连续变化，Modal组件也只会在"移动端/桌面端"发生真切换时才重新渲染相关分支。

另一个印证点在 hooks/useSummarize.ts（BibiGPT-v1 的 AI 总结核心 Hook）：错误处理 Effect 的依赖是[error, showSingIn, toast]——全部是原始类型或稳定引用，并且在 Effect 内部用早返回先过滤无错误分支，再按状态码分发处理：

useEffect(() => { if (!error) { return } const { statusCode, detail } = parseBackendErrorMessage(error.message || 'Unknown error') if (statusCode === 501) { /* 字幕缺失 toast */ return } if (statusCode === 504) { /* 限流 toast */ return } if (statusCode === 401) { /* 登录引导 */ return } toast({ variant: 'destructive', title: 'API 请求出错，请重试。', description: detail || error.message }) }, [error, showSingIn, toast])

此外，仓库中还有多处与"减少 Effect 重复执行/消除不必要的重渲染"同族的实践：

• hooks/useLocalStorage.ts 用惰性初始化（useState(() => …)）让JSON.parse(localStorage.getItem(key))只在首次渲染执行一次——对应规则rerender-lazy-state-init；
• components/CommandMenu.tsx 在keydown监听里使用函数式 setStatesetOpen((open) => !open)，避免闭包捕获陈旧值，对应规则rerender-functional-setstate；
• components/shared/leaflet.tsx 的动画启动 Effect 依赖为空数组[]，明确"仅在挂载时执行一次"，属于对挂载时机类 Effect 的依赖收窄。

与依赖收窄配套的兄弟规则

依赖收窄不是孤立的，Vercel 规则集在rerender-前缀下围绕"Effect 与重渲染"给出了一整套配套范式，收窄依赖时常常需要它们协同：

例如rerender-derived-state-no-effect中的典型反例——在 Effect 里拼接fullName再setFullName——就是"依赖收窄"解决不了的场景，因为问题不在依赖过宽，而在根本不该用 Effect 同步派生值，直接改成渲染期计算const fullName = firstName + ' ' + lastName才是正解：

// 错误：多余 state + Effect 同步，引发二次渲染 const [fullName, setFullName] = useState('') useEffect(() => { setFullName(firstName + ' ' + lastName) }, [firstName, lastName]) // 正确：渲染期派生，无 Effect、无额外 state const fullName = firstName + ' ' + lastName

同理，rerender-move-effect-to-event强调：提交表单这类一次性动作如果被建模成"state + Effect"，会让 Effect 在主题等无关依赖变化时重复执行、甚至重复提交。应直接把副作用写进handleSubmit事件处理器。综合来看，判断顺序应当是：能进事件处理器就不进 Effect；能在渲染期派生就不进 Effect；必须在 Effect 里的，依赖收窄到最小原始字段。

实操：代码审查与重构检查清单

将本规则落地为可执行的审查习惯，可按以下顺序逐条核查代码中的useEffect：

1. 依赖是否只有"Effect 内实际读到的值"？逐行检查 Effect 函数体，删去只被"顺手写进数组"但没有读到的依赖。
2. 依赖是对象还是原始字段？若 Effect 只读取user.id、config.model这类字段，把依赖从对象收窄到字段；必要时在 Effect 开头先解构/提取所需字段。
3. 是否存在"连续数值依赖 + 布尔判断"？如width < 768、scrollY > 0这类判断，先把表达式提为渲染期的派生布尔常量，再把布尔量作为依赖。
4. 是否能用更彻底的方案替代？依据上文判断顺序：能否移入事件处理器？能否在渲染期派生（去掉 Effect 与额外 state）？能否用useMediaQuery、ref 或 transition 从源头规避？
5. 回归验证：对照仓库里的落地案例（use-window-size.ts 的isMobile派生、useSummarize.ts 的原始依赖 + 早返回）检查自己的写法是否同构。

小结

rerender-dependencies（Narrow Effect Dependencies）看似简单，却是 React 应用里最容易忽视、收益最稳定的性能/正确性优化点：依赖数组里的对象引用变化会让 Effect 被无关更新反复触发，而原始类型依赖与渲染期派生布尔值能让 Effect 只在真正有意义的状态跳变时执行。在 BibiGPT-v1 中，use-window-size对外只暴露isMobile/isDesktop布尔值、useSummarize以原始依赖加早返回处理错误，都是这一规则的工程化范例。将该规则与rerender-derived-state、rerender-move-effect-to-event等兄弟规则组合使用，即可形成一套完整的"Effect 最小化"重构方法论。

• 人工智能
• 大模型
• AI 应用
• 前端
• 后端