vuex-persistedstate 是轻量 Vuex 插件，将 state 持久化至 localStorage 等介质，支持按路径、过滤器、自定义存储及多介质适配，需注意序列化限制与跨标签页同步。
vuex-persistedstate 是一个轻量、易用的 Vuex 插件，用于将 Vuex 的 state 持久化到浏览器的 localStorage（或 sessionStorage、cookie 等）中，页面刷新后状态不丢失。它不侵入你的 store 结构，只需简单配置即可生效。
安装与基础配置
先通过 npm 或 yarn 安装：
npm install vuex-persistedstate
然后在创建 Vuex store 时引入并作为插件注册：
立即学习“前端免费学习笔记（深入）”；
```js
import { createStore } from 'vuex'
import createPersistedState from 'vuex-persistedstate'
export default createStore({
state: { count: 0, userInfo: null },
mutations: {
SET_COUNT(state, n) { state.count = n },
SET_USER(state, user) { state.userInfo = user }
},
plugins: [
createPersistedState()
]
)
```
默认情况下，它会把整个 state 序列化后存入 localStorage，key 为 vuex。
按需持久化指定模块或字段
实际项目中通常不需要缓存全部 state，比如 token 可以缓存，但临时表单数据或 loading 状态就不该持久化。可通过以下方式精细化控制：
-
只保存特定模块：用
paths指定路径，如['user.token', 'cart.items'] -
排除敏感字段：配合
filter函数，跳过含 password、token 的对象属性 -
自定义存储位置：用
key改变 localStorage 的键名，避免多个项目冲突
示例：
```js
createPersistedState({
key: 'myapp-vuex',
paths: ['user.profile', 'settings.theme'],
filter: (mutation) => {
return !mutation.type.startsWith('temp/') // 过滤临时 mutations
}
)
```
支持多种存储介质
默认使用 localStorage，但也可切换为 sessionStorage（关闭标签页即清除）、IndexedDB（适合大数据）或自定义存储器：
- 用
storage选项替换默认存储对象，例如：storage: window.sessionStorage - 结合
js-cookie实现 cookie 存储（注意大小限制和安全设置） - 使用
idb-keyval等库接入 IndexedDB（需额外封装 storage 接口）
常见场景建议：
– 登录态、用户偏好 → localStorage
– 表单草稿、临时筛选 → sessionStorage
– 大型离线数据 → IndexedDB + 自定义 storage
注意事项与常见问题
使用过程中要注意几个关键点：
- state 必须可序列化：不能包含函数、Date、RegExp、undefined、Symbol 或循环引用，否则 JSON.stringify 会失败或丢数据
-
首次加载时机：插件在 store 初始化时自动从存储恢复 state，但组件 mounted 钩子可能早于 state 恢复完成，建议用
v-if="$store.state.xxx !== undefined"或加 loading 状态兜底 -
多标签页同步问题：localStorage 不触发跨标签页事件，可用
storage事件监听并手动 dispatch 同步（vuex-persistedstate 不内置该逻辑） - 版本升级清缓存：state 结构变更时，旧缓存可能引发错误，可在插件配置中加入 version 校验或启动时主动清除
例如升级时强制重置：
```js
createPersistedState({
key: 'myapp-vuex',
reducer: (state) => ({ ...state, version: '2.0' }), // 写入版本标识
filter: (mutation) => mutation.type !== 'RESET_ALL'
)
```
