Pinia刷新丢状态：localStorage与持久化插件

脚本专家

在 Vue3 项目里使用 Pinia 管理用户状态时，常见现象是：调用过 setUsername 后当前页面显示正常，但浏览器刷新后 username 又变空。原因在原文现象中已经明确：Pinia 状态默认只保存在内存，页面刷新会重新初始化 Store；Store 里虽然写了 localStorage.setItem 做保存，但初始化时没有从 localStorage 读取恢复数据。

问题定位

原有逻辑只完成了“写入”这一半：setUsername 修改 username 并写入 localStorage，clearUser 清空 username 并移除 localStorage；但 username 初始值仍是 ref('')。因此刷新时 Store 重新创建，值回到空字符串，已经保存到 localStorage 的数据没有被读回。

方案一：手动补全初始化读取

如果当前只有 username 一个字段需要持久化，不需要安装插件，直接修改 stores/user.ts，把初始值改为从 localStorage 读取，没有值时回退为空字符串：

2. import { defineStore } from 'pinia'
3. import { ref } from 'vue'
5. export const useUserStore = defineStore('user', () => {
6.   // 初始化时从 localStorage 读取，没有则默认空字符串
7.   const username = ref(localStorage.getItem('username') || '')
9.   function setUsername(name: string) {
10.     username.value = name
11.     localStorage.setItem('username', name)
12.   }
14.   function clearUser() {
15.     username.value = ''
16.     localStorage.removeItem('username')
17.   }
19.   return { username, setUsername, clearUser }
20. })

复制代码

这段改动的核心只有初始化表达式：ref('') 改为 ref(localStorage.getItem('username') || '')。刷新后重新初始化 Store 时，会先从 localStorage 读取之前保存的用户名；setUsername 和 clearUser 仍分别负责写入和删除。适用场景是持久化字段很少、逻辑简单，手动维护读写成本低。

方案二：使用 pinia-plugin-persistedstate 插件

如果后续还要持久化 token、权限等更多状态，逐个字段手写 localStorage 容易遗漏。原文推荐使用 pinia-plugin-persistedstate，由插件自动处理存取。

第一步，安装插件：

2. npm install pinia-plugin-persistedstate

复制代码

第二步，在 main.ts 中创建 Pinia 实例并注册插件：

2. import { createApp } from "vue";
3. import { createPinia } from "pinia";
4. import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
5. import App from "./App.vue";
6. import router from "./router/index.ts";
8. const app = createApp(App);
9. const pinia = createPinia();
10. pinia.use(piniaPluginPersistedstate); // 注册持久化插件
11. app.use(pinia);
12. app.use(router);
13. app.mount("#app");

复制代码

第三步，在 Store 的第二个参数中开启 persist：

2. import { defineStore } from 'pinia'
3. import { ref } from 'vue'
5. export const useUserStore = defineStore('user', () => {
6.   const username = ref('')
8.   function setUsername(name: string) {
9.     username.value = name
10.   }
12.   function clearUser() {
13.     username.value = ''
14.   }
16.   return { username, setUsername, clearUser }
17. }, {
18.   persist: true // 开启持久化，自动存入 localStorage
19. })

复制代码

开启后，username 变化时插件会自动写入 localStorage，页面刷新时自动读取恢复，Store 内不再需要手写 localStorage.setItem 和 localStorage.getItem。与方案一相比，方案二把持久化逻辑交给插件统一处理，更适合状态字段会持续增加的项目。

选择建议

当前只有 username 一个字段时，方案一只需改一行初始化代码，改动最小；如果后续还有 token、权限等更多状态需要持久化，方案二可以减少重复的手动读写代码，避免新增字段时漏掉初始化读取。两种方案都围绕同一个根因：Pinia 状态在内存中，刷新会重建，必须显式从 localStorage 恢复，或由持久化插件完成自动恢复。

热心网友6

楼主这篇把根因和两条路都讲透了，写得很清楚。补充几个我踩过的坑，算是给后来人省点时间： 第一，方案一那种写法在纯 SPA 里没问题，但如果项目以后上 SSR 或 Nuxt，`localStorage` 在服务端不存在，初始化时直接访问会报错，得加个判断或者放到 onMounted / 客户端钩子里读。哪怕暂时不做 SSR，也建议写成 `typeof localStorage !== 'undefined' ? ... : ''` 兜一下，成本很低。 第二，如果你持久化的不是字符串而是对象或数组，读回来一定要记得 `JSON.parse`，并且外面包一层 try/catch。localStorage 里的值可能被用户手动改坏或者版本升级后结构对不上，直接 parse 抛异常会让整个 Store 初始化失败，白屏很难排查。 第三，方案二插件默认是用 store 的 id 作为 storage key，也就是 `user`。如果以后同一域名下有几个子系统共用 localStorage，容易撞 key，建议显式指定 `key`，比如 `key: 'app-user'`。另外字段多了以后没必要全量持久化，可以用 `pick` 只挑需要存的，token、权限这些敏感点的也尽量考虑放 sessionStorage 而不是 localStorage，减少 XSS 场景下的暴露面。 第四，用插件的时

热心网友5

楼主的定位很清楚，根因就是 Pinia 状态只在内存里，刷新重建 Store 后只写了 localStorage 却没有读回来。方案一只改初始化表达式，适合当前只有 username 的场景，改动小也直观；方案二用插件接管持久化，后续 token、权限等字段变多时更省心，选择建议也挺合理。实际项目里我会先用方案一把当前问题解决，等持久化字段多起来再迁到插件，避免过早增加依赖。

热心网友7

这个定位说得很到位，Pinia 状态只在内存里，刷新就重建，只写了 set 没做初始化读取，确实是很容易踩的坑。方案一改一行初始化确实最省事，只有 username 一个字段时完全够用；方案二上插件对后面还要加 token、权限这些字段的项目更友好，省得每加一个字段都得记得补读写逻辑。我自己也遇到过类似情况，当时就是只写了 localStorage.setItem 忘了读回来，排查半天才发现问题在 Store 初始值上。感谢分享，两种方案的取舍讲得挺清楚的。