zustand

Zustand 状态管理

概览

Zustand v5 是一个基于 useSyncExternalStore 构建的轻量级 React 全局状态管理器。需要 React 18+（内部使用 useSyncExternalStore）。使用 createWithEqualityFn 时，请将 use-sync-external-store 安装为对等依赖。它提供类型安全的 store、可最大限度减少重新渲染的原子选择器、可组合的中间件（persist、devtools、immer、subscribeWithSelector），以及适用于大型应用的切片模式。客户端专用全局状态请使用 Zustand；服务端获取的数据请使用 TanStack Query。

适用场景： 客户端全局状态、持久化用户偏好设置、复杂的多领域 store、跨组件状态共享、vanilla（非 React）状态管理。

不适用场景： 需要缓存的服务端状态（请使用 TanStack Query）、单组件状态（请使用 useState）、简单的 prop 层层传递场景。

快速参考

模式	API	要点
基础 store	create<T>()((set) => ({...}))	TypeScript 需要双括号
原子选择器	useStore(state => state.bears)	仅在选中的值发生变化时重新渲染
多个值	useShallow(state => ({a, b}))	从 zustand/react/shallow 导入
持久化	persist(fn, { name })	使用 localStorage，并处理 SSR 水合
Devtools	devtools(fn, { name })	集成 Redux DevTools
SubscribeWithSelector	subscribeWithSelector(fn)	在 React 之外订阅状态切片
中间件顺序	devtools(persist(fn))	从外层到内层包装
切片模式	StateCreator<Combined, [], [], Slice>	按领域拆分 store
SSR Provider	createStore + React Context	每个请求使用独立 store，防止数据泄漏
Immer	immer(fn)	安全地修改嵌套状态
Vanilla store	createStore from zustand/vanilla	在 React 之外使用
重置 store	set(store.getInitialState())	使用 getInitialState() 可靠地重置
派生值	useStore(s => s.items.length)	在选择器中计算
自动选择器	createSelectors(store)	自动生成 store.use.field() hook

常见错误

错误	正确做法
使用带一层括号的 create<T>(...)	使用带两层括号的 create<T>()(...)，以正确推断 TypeScript 中间件类型
使用 useStore(state => state) 选择完整状态对象	使用 state.bears 等原子选择器或 useShallow，避免不必要的重新渲染
从 zustand/shallow 导入 useShallow	从 zustand/react/shallow 导入；zustand/shallow 仅导出普通的 shallow 函数
在选择器中创建新的对象引用，导致无限循环	使用单独的基本类型选择器，或用 zustand/react/shallow 中的 useShallow 包装
在 SSR 或 Next.js 中使用全局单例 store	使用 StoreContext provider 模式与 createStore，防止请求之间的数据泄漏
手动跟踪初始状态以进行重置	使用 Zustand 自动提供的 store.getInitialState()
使用 Zustand 管理需要缓存和重新验证的服务端获取数据	使用 TanStack Query 管理服务端状态；Zustand 仅用于客户端全局状态

委派

• Store 架构与切片设计：使用 Plan Agent 定义领域边界、切片接口和中间件组合顺序
• Hydration 与 SSR 调试：使用 Task Agent 诊断 persist 中间件问题、hydration 不匹配以及 Next.js provider 配置
• 从 v4 迁移到 v5：使用 Explore Agent 查找已弃用的导入路径、单层括号写法和旧版中间件用法
• 测试策略：使用 Task Agent 设置 store 模拟和测试隔离模式

参考资料

• Store 模式、TypeScript 和核心 API
• 中间件：persist、devtools、immer、subscribeWithSelector 和自定义中间件
• 切片模式与大型 Store 架构
• SSR、Next.js 与 hydration 处理
• 使用 Vitest 和 Jest 测试 store
• 迁移指南：Redux、Context 以及从 v4 迁移到 v5