Vue3迁移后vuex-persist无法写入localStorage问题排查

核心原因与解决方案 #

1. 依赖版本兼容性问题 #

Vue3 对应使用 Vuex 4.x，旧版 vuex-persistedstate 仅支持适配 Vue2 的 Vuex 3.x。首先确认依赖版本：

• 确保 vuex 版本为 ^4.0.0 或更高
• 确保 vuex-persistedstate 版本为 ^3.1.3 或更高（该版本开始支持 Vuex 4）

版本不匹配的话，重新安装适配版本：

npm install vuex@4 vuex-persistedstate@latest

2. 插件配置方式错误 #

Vue3 中 Vuex 通过 createStore 创建实例，插件需直接在 store 配置的 plugins 数组中注册，而非 Vue2 时代的 Vue.use 方式。正确配置示例：

// store/index.js
import { createStore } from 'vuex'
import createPersistedState from 'vuex-persistedstate'

export default createStore({
  state: {
    userInfo: null,
    theme: 'light'
  },
  mutations: {
    SET_USER_INFO(state, payload) {
      state.userInfo = payload
    }
  },
  actions: {},
  modules: {},
  // 注册持久化插件
  plugins: [
    createPersistedState({
      storage: window.localStorage,
      // 可选：指定需要持久化的状态路径，默认全部持久化
      paths: ['userInfo', 'theme'],
      // 关键：开启后初始化时自动将初始状态写入localStorage
      writeInitialState: true
    })
  ]
})

3. 初始状态写入逻辑差异 #

Vue2 中旧版 vuex-persistedstate 默认在 store 初始化时自动写入初始状态，而 Vue3 对应的新版本为优化性能，默认关闭了该行为（writeInitialState 默认值为 false）。若需启动时就存入初始状态，必须显式设置 writeInitialState: true。

4. 应用初始化流程验证 #

确保 main.js 中正确挂载 store：

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import store from './store'

const app = createApp(App)
app.use(store)
app.mount('#app')

版本差异原因 #

• Vue2 的 new Vue() 初始化流程会触发 Vuex 插件的早期生命周期钩子，旧版插件借此完成初始状态写入。
• Vue3 的 createApp + app.use(store) 调整了插件执行时机，且新版插件默认不自动写入初始状态，需手动开启 writeInitialState 选项。

内容的提问来源于stack exchange，提问作者Saptarshi