使用持久化中间件保存状态
使用 persist 中间件将 Zustand 状态同步到 localStorage 或 sessionStorage。
使用持久化中间件保存状态 是 CoddyKit 上的免费 React Academy 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Academy 课程共包含 4 节课。
欢迎
在本课中，您将使用 Zustand 的 persist 中间件自动将 store 状态同步到 localStorage，使状态在页面重新加载后仍然保留。
为什么要持久化状态？
如果没有持久化，用户刷新页面时所有 store 状态都会重置。将购物车项目、用户偏好或界面状态（如打开的面板）持久化到 localStorage，可以让用户在不同会话之间获得流畅的体验。
persist 中间件
使用 persist() 包装 create() 调用，并提供唯一的存储键。Zustand 会在挂载时自动从 localStorage 读取数据，并在每次状态变化时写入数据。
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
const useCartStore = create(
persist(
(set) => ({
items: [],
addItem: (item) => set(s => ({ items: [...s.items, item] })),
}),
{ name: 'cart-storage' } // localStorage key
)
);使用 partialize 进行部分持久化
使用 `partialize` 只持久化 store 中的特定切片。这样可以将临时数据（例如加载标志）排除在 localStorage 之外。
persist(
(set) => ({ user: null, token: null, loading: false, fetch: () => {} }),
{
name: 'auth-storage',
partialize: (state) => ({ user: state.user, token: state.token }),
// loading and fetch are NOT persisted
}
)使用 sessionStorage
如果只希望在浏览器会话期间持久化数据（关闭标签页时清除），请将 `createJSONStorage(() => sessionStorage)` 作为存储选项传入。
import { createJSONStorage } from 'zustand/middleware';
persist(storeCreator, {
name: 'session-data',
storage: createJSONStorage(() => sessionStorage),
})版本控制与迁移
当 store 的结构发生变化（新增字段或重命名键）时，请设置 `version` 编号，并提供 `migrate` 函数来升级旧的持久化数据。
persist(storeCreator, {
name: 'my-store',
version: 2,
migrate: (persistedState, version) => {
if (version === 1) {
return { ...persistedState, newField: 'default' };
}
return persistedState;
},
})水合与 SSR
在服务器端（Next.js）不存在 localStorage。Zustand 的 persist 中间件会妥善处理这种情况：它会跳过服务器端水合，并在客户端挂载后重新水合。
onRehydrateStorage 回调
使用 `onRehydrateStorage` 在 store 从存储中恢复时运行代码。这对于在令牌恢复后触发接口调用很有用。
persist(storeCreator, {
name: 'auth',
onRehydrateStorage: () => (state) => {
if (state?.token) state.fetchUser();
},
})清除持久化状态
调用 `useMyStore.persist.clearStorage()` 可从 localStorage 中移除持久化数据，这对于退出登录流程很有用。
const handleLogout = () => {
useAuthStore.persist.clearStorage();
useAuthStore.setState({ user: null, token: null });
};存储大小限制
localStorage 每个来源的容量限制为 5–10 MB。请避免持久化大型数据集（例如完整的产品目录），只持久化标识符或较小的配置对象。
快速检查
persist 中间件中的哪个选项可以排除某些状态字段，使其不被保存到 localStorage？
回顾
使用 persist() 包装 Zustand store，并提供 name 键。使用 partialize 只存储相关切片。当 store 结构发生变化时，请进行版本控制并迁移。退出登录时使用 clearStorage()。
接下来
下一课：**Zustand DevTools 与 store 测试**——您将连接 Redux DevTools，并为 Zustand 操作编写单元测试。
常见问题解答
「使用持久化中间件保存状态」课时是免费的吗？
是的 — 「使用持久化中间件保存状态」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Academy 课程共包含 4 节课。
「使用持久化中间件保存状态」这节课中我会学到什么？
使用 persist 中间件将 Zustand 状态同步到 localStorage 或 sessionStorage。 你通过在浏览器中直接运行的动手代码来练习 React Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 React Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 React Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「使用持久化中间件保存状态」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 React Academy 课中编写并运行代码吗？
能。每节 React Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。