💾 Vuex Persist 状态持久化完全指南

Vue2 版本的项目一般都使用官方的 Vuex 状态管理库，但是 Vuex 在页面刷新后，会进行初始化而丢失数据，Vuex Persist 是为了解决这个问题而生。

📖 概述

Vuex Persist 是一个轻量级的 Vuex 插件，旨在实现 Vuex store 数据的本地存储，通常使用浏览器的 localStorage 或 sessionStorage，从而在页面刷新时能够保留应用的状态。这个项目对于希望在前端应用中保持状态跨页面或刷新的开发者而言是极其有用的工具。

✨ 主要特性

特性	描述
🔄 自动持久化	自动将 Vuex 状态保存到本地存储
🎯 选择性存储	可以选择性地持久化特定模块或状态
🚀 零配置	开箱即用，无需复杂配置
💾 多存储支持	支持 localStorage、sessionStorage 等
🔧 灵活配置	提供丰富的配置选项

📦 安装使用

🔧 安装依赖

# 使用 npm
npm install vuex-persist

# 使用 yarn
yarn add vuex-persist

# 使用 pnpm
pnpm add vuex-persist

⚙️ 基础配置

// 引入依赖包
import VuexPersistence from 'vuex-persist'

// 创建持久化实例
const vuexLocal = new VuexPersistence({
  // 使用 localStorage 保存 vuex 的数据，刷新不会丢失
  storage: window.localStorage,
  
  // 如果不用这个函数指定，那么默认所有 vuex 数据都作持久化处理
  reducer(val) {
    return {
      user: val.user, // 这里只对 user 模块作数据持久化
      preferences: val.preferences
    }
  }
})

// 添加到 vuex 的 plugins 插件中
const store = new Vuex.Store({
  state: { 
    // ... 
  },
  mutations: { 
    // ... 
  },
  actions: { 
    // ... 
  },
  modules: {
    user,
    preferences,
    // ...
  },
  plugins: [vuexLocal.plugin]
})

💡 配置说明

• storage: 指定存储方式，可选 localStorage、sessionStorage
• reducer: 选择性持久化，只保存指定的状态模块
• plugins: 将插件添加到 Vuex store 的插件数组中

🔧 高级配置

📋 完整配置选项

const vuexPersist = new VuexPersistence({
  // 存储键名
  key: 'vuex',
  
  // 存储方式
  storage: window.localStorage,
  
  // 选择性持久化
  reducer: (state) => ({
    user: state.user,
    settings: state.settings
  }),
  
  // 过滤器函数
  filter: (mutation) => {
    // 只有特定的 mutation 才会触发持久化
    return mutation.type === 'updateUser'
  },
  
  // 异步存储
  asyncStorage: false,
  
  // 支持模块
  modules: ['user', 'settings'],
  
  // 严格模式
  strictMode: false,
  
  // 支持 Promise
  supportCircular: false
})

🎯 选择性持久化示例

// 场景1: 只持久化用户信息和偏好设置
const userPersist = new VuexPersistence({
  storage: window.localStorage,
  reducer: (state) => ({
    user: {
      token: state.user.token,
      profile: state.user.profile
    },
    preferences: state.preferences
  })
})

// 场景2: 使用 sessionStorage 进行会话级持久化
const sessionPersist = new VuexPersistence({
  storage: window.sessionStorage,
  modules: ['cart', 'currentOrder']
})

// 场景3: 多个持久化实例
const store = new Vuex.Store({
  // ... store 配置
  plugins: [
    userPersist.plugin,
    sessionPersist.plugin
  ]
})

🌟 实际应用场景

🛒 电商购物车

// 购物车持久化
const cartPersist = new VuexPersistence({
  key: 'shopping-cart',
  storage: window.localStorage,
  reducer: (state) => ({
    cart: {
      items: state.cart.items,
      total: state.cart.total
    }
  })
})

const store = new Vuex.Store({
  modules: {
    cart: {
      state: {
        items: [],
        total: 0
      },
      mutations: {
        ADD_TO_CART(state, product) {
          state.items.push(product)
          state.total += product.price
        },
        CLEAR_CART(state) {
          state.items = []
          state.total = 0
        }
      }
    }
  },
  plugins: [cartPersist.plugin]
})

👤 用户认证状态

// 用户认证持久化
const authPersist = new VuexPersistence({
  key: 'auth-state',
  storage: window.localStorage,
  reducer: (state) => ({
    auth: {
      token: state.auth.token,
      user: state.auth.user,
      isAuthenticated: state.auth.isAuthenticated
    }
  }),
  filter: (mutation) => {
    // 只在登录、登出时触发持久化
    return ['LOGIN_SUCCESS', 'LOGOUT'].includes(mutation.type)
  }
})

⚙️ 应用设置

// 应用设置持久化
const settingsPersist = new VuexPersistence({
  key: 'app-settings',
  storage: window.localStorage,
  modules: ['settings'],
  filter: (mutation) => {
    return mutation.type.startsWith('settings/')
  }
})

🔍 最佳实践

✅ 推荐做法

🎯 最佳实践

1. 选择性持久化: 只持久化必要的状态，避免存储过多数据
2. 敏感数据处理: 不要持久化敏感信息如密码等
3. 存储容量管理: 定期清理过期或无用的持久化数据
4. 错误处理: 添加适当的错误处理机制
5. 版本兼容: 考虑应用版本升级时的数据兼容性

🚫 避免的做法

⚠️ 注意事项

• 不要持久化所有状态，会导致存储空间浪费
• 避免持久化临时状态如 loading、error 等
• 不要在持久化数据中存储函数或复杂对象
• 注意浏览器存储限制（localStorage 通常 5-10MB）

🔧 错误处理

const vuexPersist = new VuexPersistence({
  storage: window.localStorage,
  reducer: (state) => ({ user: state.user }),
  
  // 添加错误处理
  restoreState: (key, storage) => {
    try {
      const data = storage.getItem(key)
      return data ? JSON.parse(data) : undefined
    } catch (error) {
      console.error('Failed to restore state:', error)
      // 清除损坏的数据
      storage.removeItem(key)
      return undefined
    }
  },
  
  saveState: (key, state, storage) => {
    try {
      storage.setItem(key, JSON.stringify(state))
    } catch (error) {
      console.error('Failed to save state:', error)
    }
  }
})

🚀 与其他技术集成

🔄 Vue 3 + Pinia 替代方案

// 对于 Vue 3 项目，推荐使用 Pinia 的持久化插件
import { createPinia } from 'pinia'
import { createPersistedState } from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(createPersistedState())

🌐 与 Vue Router 集成

// 结合路由守卫使用
const store = new Vuex.Store({
  // ... store 配置
  plugins: [vuexPersist.plugin]
})

// 在路由守卫中检查认证状态
router.beforeEach((to, from, next) => {
  const isAuthenticated = store.state.auth.isAuthenticated
  
  if (to.meta.requiresAuth && !isAuthenticated) {
    next('/login')
  } else {
    next()
  }
})

📊 性能考虑

⚡ 优化建议

优化方案	描述	适用场景
按需持久化	只持久化必要的状态	所有项目
数据压缩	压缩存储的 JSON 数据	大量数据存储
异步存储	使用异步存储避免阻塞	高频更新场景
定期清理	定期清理过期数据	长期运行应用

🌟 总结

Vuex Persist 在 Vue 生态系统中广泛应用于任何依赖 Vuex 状态管理的项目，尤其适合：

• ✅ 单页应用 (SPA): 保持页面刷新后的状态
• ✅ 管理后台系统: 维持用户登录状态和偏好设置
• ✅ 电商应用: 持久化购物车和用户偏好
• ✅ 多视图应用: 确保各个视图状态一致性

通过合理配置和使用 Vuex Persist，可以显著提升用户体验，确保应用状态的持久化和一致性。