• 前端
• UI组件

在基于 Next.js 16、React 19 与 shadcn/ui 构建的 next-shadcn-dashboard-starter 管理后台中，列表型状态（任务看板、通知中心、会话列表）无处不在。本文以 Vercel Engineering 维护的 React 最佳实践规则 rerender-functional-setstate.md 为核心骨架，系统讲解"基于当前状态更新时为何必须使用函数式 setState"，并结合仓库内看板、通知、聊天等真实 Zustand store 实现，帮助你在编写或重构组件时彻底规避过期闭包（stale closure）问题、稳定回调引用并减少子组件重渲染。

规则定位：Re-render Optimization 类别中的 MEDIUM 级优化项

在 Vercel 的 64 条 React/Next.js 性能指南中（见 SKILL.md），本规则rerender-functional-setstate隶属于第 5 优先级类别 Re-render Optimization，影响级别为MEDIUM，其影响描述为 "prevents stale closures and unnecessary callback recreations"——即防止过期闭包与不必要的回调重建。

该规则的核心主张可以浓缩为一句话：

当更新状态依赖当前状态值时，应使用 setState 的函数式更新形式（updater），而不是直接引用状态变量。

这不仅是代码风格问题，它直接关系到三件事：闭包是否会读到旧值、useCallback的依赖数组是否需要频繁变动、以及子组件是否会因此被无意义地重渲染。

问题剖析：为什么直接引用状态变量是有风险的

先看规则给出的反例（取自原文档，原样保留）：

function TodoList() { const [items, setItems] = useState(initialItems); // Callback must depend on items, recreated on every items change const addItems = useCallback( (newItems: Item[]) => { setItems([...items, ...newItems]); }, [items] ); // ❌ items dependency causes recreations // Risk of stale closure if dependency is forgotten const removeItem = useCallback((id: string) => { setItems(items.filter((item) => item.id !== id)); }, []); // ❌ Missing items dependency - will use stale items! return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />; }

这段代码同时暴露了两类典型问题：

1. 依赖数组被迫膨胀（addItems）：由于回调体内部引用了items变量，useCallback的依赖数组必须包含items。结果就是每次items发生变化（哪怕与本次操作无关），addItems都会被重建，进而使<ItemsEditor />这类经过 memo 优化的子组件收到新的onAdd引用而被迫重渲染。

2. 过期闭包隐患（removeItem）：如果开发者"忘写"了items依赖（依赖数组为[]），回调闭包会永远捕获首次渲染时的items值。后续点击删除按钮时，删除操作会基于一份早已过期的列表进行——典型表现为"删不掉"、"误删"或"删完之后列表又恢复原状"等诡异 bug。这正是 React 社区中最常见的闭包类错误来源之一。

正确姿势：用函数式更新换取稳定引用与最新状态

规则给出的正确实现如下（同样原样保留）：

function TodoList() { const [items, setItems] = useState(initialItems); // Stable callback, never recreated const addItems = useCallback((newItems: Item[]) => { setItems((curr) => [...curr, ...newItems]); }, []); // ✅ No dependencies needed // Always uses latest state, no stale closure risk const removeItem = useCallback((id: string) => { setItems((curr) => curr.filter((item) => item.id !== id)); }, []); // ✅ Safe and stable return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />; }

两处关键改动：

• 不再在回调体内读取items，改为通过 updater 参数curr（当前最新状态）来计算新值；
• 依赖数组清空为[]，回调从此在组件整个生命周期内只创建一次，引用恒定。

React 保证 updater 函数在调度时总会拿到当时最新的 state，无论回调是什么时候被创建的。因此无论函数被引用多久、被传递到哪里，它操作的一定是最新状态。

收益清单：为什么这是值得固化的工程习惯

原文档总结了四条收益，这里逐一展开：

1. 稳定的回调引用（Stable callback references）：状态变化不再导致useCallback/useMemo重建，配合React.memo可以真正减少子组件重渲染。这在列表、表格、表单字段这类高频交互 UI 中收益尤其明显。
2. 没有过期闭包（No stale closures）：updater 总是基于最新状态计算，彻底消除了"回调记住旧值"这一 React 闭包 bug 的第一大来源。
3. 更少的依赖项（Fewer dependencies）：依赖数组变得更短、更纯粹，代码更易阅读，也降低了因依赖写错/漏写而引发内存泄漏或行为异常的概率。
4. 预防 bug（Prevents bugs）：从机制上消灭最常见的 React 闭包错误，而不是依赖开发者的细心。

使用边界：何时必须用函数式更新，何时直接赋值即可

原文档给出了清晰的判定标准，是实战中最常被询问的部分：

应当使用函数式更新的场景：

• 任何依赖当前状态值的setState调用；
• 在useCallback/useMemo内部需要读取状态时；
• 引用状态的事件处理器（onClick、onChange 等回调）；
• 异步操作（定时器、请求回调、setTimeout）中更新状态——此时闭包捕获旧值的风险最高。

可以直接赋值的场景：

• 设置静态值：setCount(0)；
• 只依赖参数/props 赋值：setName(newName)；
• 新状态与旧状态完全无关。

一个实用的记忆方式是：只要更新逻辑里出现了"旧的 state 变量"，就应改写为 updater 形式。

仓库实战：看板、通知与聊天 store 中的函数式更新范式

规则文件本身给出了组件层示例，而在 next-shadcn-dashboard-starter 中，函数式更新的思想还被一致地贯彻到了全局状态管理（Zustand）的 action 实现中。以下三处是最典型的印证。

看板：向 backlog 列头部插入新任务

src/features/kanban/utils/store.ts 中的addTask采用set((state) => ...)函数式更新，在保留原有任务列表的前提下向backlog列头部插入新任务：

addTask: (title, description) => set((state) => ({ columns: { ...state.columns, backlog: [ { id: uuid(), title, description, priority: 'medium' as Priority, assignee: undefined, dueDate: undefined }, ...(state.columns.backlog ?? []) ] } }))

如果这里改写成setColumns加直接引用columns变量的形式，一旦多个拖拽/新增动作并发或异步触发，就会面临与组件层完全相同的过期快照问题。

通知中心：基于旧列表的映射与过滤

src/features/notifications/utils/store.ts 中的四个 action 全部使用函数式更新：

markAsRead: (id) => set((state) => ({ notifications: state.notifications.map((n) => n.id === id ? { ...n, status: 'read' as const } : n ) })), removeNotification: (id) => set((state) => ({ notifications: state.notifications.filter((n) => n.id !== id) })), addNotification: (notification) => set((state) => ({ notifications: [{ ...notification, status: 'unread' as const }, ...state.notifications] }))

markAsRead（按 id 映射）、removeNotification（按 id 过滤）、addNotification（头部插入）三者都依赖"当前 notifications"来计算新值，函数式更新保证每次操作都基于最新列表。

聊天：多字段联动的状态推进

src/features/chat/utils/store.ts 中selectConversation与addIncomingMessage同样采用函数式更新，在一个 updater 内同时维护selectedConversationId、conversations与unread计数的一致性；advanceReplyCursor则基于state.replyCursor递增回复游标，是"计数器型函数式更新"的典型用例：

advanceReplyCursor: (conversationId) => set((state) => ({ replyCursor: { ...state.replyCursor, [conversationId]: (state.replyCursor[conversationId] ?? 0) + 1 } })),

值得注意的是：与useState的 updater 类似，Zustand 的set((state) => ...)同样接收最新状态快照，因此上述模式在异步消息到达、多 tab 场景下依然安全。这也说明"函数式更新"是跨越组件状态与全局 store 的统一工程原则。

组件层：useCallback 的稳定依赖实践

在 UI 组件库中也能看到依赖数组的克制用法。src/components/ui/kanban.tsx 中getItemValue仅依赖getItemValueProp，getColumn依赖[value, getItemValue]——依赖被严格限定在真正读取的外部变量上，而不是把整个状态快照拖进闭包。这与本规则"减少依赖、稳定引用"的目标一致。

与 React Compiler 的关系

原文档在结尾给出了重要补充：如果项目启用了 React Compiler（React 官方编译器），编译器可以自动优化部分场景（如自动记忆化、自动处理部分依赖）。但即便启用了编译器，函数式更新依然是推荐写法——因为它从根本上保证正确性、防止过期闭包，且不依赖编译器的优化是否覆盖到具体分支。对 next-shadcn-dashboard-starter 这类大型模板项目而言，把函数式更新作为默认习惯，比寄希望于编译器兜底更稳健。

相关规则联动：构建完整的重渲染优化心智

本规则并非孤立存在。在 Re-render Optimization 类别中，它与以下规则共同构成一套完整打法（参见 SKILL.md 第 5 类）：

• rerender-lazy-state-init：为昂贵初始值传入函数形式的useState，避免初始化逻辑在每次渲染时重复执行（规则文件见 rerender-lazy-state-init.md）；
• rerender-memo/rerender-simple-expression-in-memo：将昂贵组件提取并用 memo 包裹、对简单原语避免过度 memo；
• rerender-derived-state/rerender-derived-state-no-effect：订阅派生布尔值、在渲染期间而非 effect 中派生状态；
• rerender-dependencies：effect 依赖优先使用原始值。

函数式 setState 解决的是"回调引用稳定性与闭包正确性"这一环节；与上述规则配合，即可从"状态来源 → 派生计算 → 回调传递 → 子组件消费"全链路压低不必要的重渲染。

小结

在 next-shadcn-dashboard-starter 中，无论是组件内useState还是全局 Zustand store，"基于旧状态计算新状态"的更新都应当遵循函数式更新原则：

• 组件层：setItems((curr) => ...)+useCallback空依赖数组，获得恒定的回调引用；
• store 层：set((state) => ...)，保证异步与并发场景下的最新快照；
• 判定标准：更新逻辑中出现旧状态变量即改函数式；纯静态赋值、纯参数赋值则无需。

该实践已固化在仓库的 Vercel React 最佳实践规则（.agents/skills目录下有一份同内容的副本）中，并可在 看板 store、通知 store 与 聊天 store 中直接看到生产级落地范例，可作为你重构现有代码时对照的基准。

• 前端
• UI组件