Vue / 系统课时
持久化必要状态
持久化必要状态
管理后台刷新后应保留主题、侧栏和少量身份展示信息,但缓存不能无限有效,更不能把敏感凭据直接写入浏览器存储。本课将实现带版本号、过期时间和迁移逻辑的 Pinia 持久化方案。
学习目标
- 区分适合持久化、只应驻留内存和必须由服务端保存的状态
- 为缓存增加版本、过期时间和迁移逻辑
- 在退出登录、版本升级和缓存损坏时安全清理状态
先划定持久化边界
适合写入 localStorage 的状态应同时满足两个条件:刷新后仍有价值,泄露后不会直接扩大账号权限。主题模式、侧栏折叠、内容密度、语言偏好,以及用于界面展示的最小身份信息通常符合要求。
访问令牌、刷新令牌、密码、验证码、完整权限集合和敏感业务数据不应直接持久化到 localStorage。令牌优先使用 HttpOnly Cookie 或只保存在内存中;权限应在会话恢复后重新向服务端获取,避免缓存过期权限继续生效。
| 状态 | 建议位置 | 原因 |
|---|---|---|
| 主题、布局偏好 | localStorage |
低敏感,刷新后仍需使用 |
| 用户 ID、显示名 | 可持久化最小副本 | 仅用于界面占位,不能作为鉴权依据 |
| Access Token | 内存或 HttpOnly Cookie |
降低脚本读取和长期泄露风险 |
| 菜单与权限 | 内存,登录后重新获取 | 服务端可能随时调整 |
设计带版本和过期时间的缓存
不要直接保存 Store 的整个 $state。更稳妥的做法是定义明确的缓存结构,只选择必要字段,并在外层增加 version、savedAt 和 expiresAt。读取时依次检查 JSON 是否可解析、版本是否可迁移、缓存是否过期。

下面的模块可直接放入 src/stores/appPreferences.ts。它只保存允许持久化的字段,并兼容旧版缓存。
import { defineStore } from 'pinia'
const STORAGE_KEY = 'admin:preferences'
const CACHE_VERSION = 2
const CACHE_TTL = 30 * 24 * 60 * 60 * 1000
type ThemeMode = 'light' | 'dark' | 'system'
interface PersistedStateV2 {
version: 2
savedAt: number
expiresAt: number
data: {
theme: ThemeMode
sidebarCollapsed: boolean
density: 'comfortable' | 'compact'
identity: {
userId: string
displayName: string
} | null
}
}
interface PersistedStateV1 {
version: 1
data: {
darkMode: boolean
sidebarCollapsed: boolean
userName?: string
}
}
function migrate(raw: PersistedStateV1 | PersistedStateV2): PersistedStateV2 | null {
if (raw.version === 2) return raw
if (raw.version !== 1) return null
const now = Date.now()
return {
version: 2,
savedAt: now,
expiresAt: now + CACHE_TTL,
data: {
theme: raw.data.darkMode ? 'dark' : 'light',
sidebarCollapsed: raw.data.sidebarCollapsed,
density: 'comfortable',
identity: raw.data.userName
? { userId: '', displayName: raw.data.userName }
: null,
},
}
}
function readCache(): PersistedStateV2['data'] | null {
const text = localStorage.getItem(STORAGE_KEY)
if (!text) return null
try {
const migrated = migrate(JSON.parse(text))
if (!migrated || migrated.expiresAt <= Date.now()) {
localStorage.removeItem(STORAGE_KEY)
return null
}
return migrated.data
} catch {
localStorage.removeItem(STORAGE_KEY)
return null
}
}
export const useAppPreferencesStore = defineStore('appPreferences', {
state: () => ({
theme: 'system' as ThemeMode,
sidebarCollapsed: false,
density: 'comfortable' as 'comfortable' | 'compact',
identity: null as PersistedStateV2['data']['identity'],
}),
actions: {
hydrate() {
const cached = readCache()
if (cached) this.$patch(cached)
},
persist() {
const now = Date.now()
const payload: PersistedStateV2 = {
version: CACHE_VERSION,
savedAt: now,
expiresAt: now + CACHE_TTL,
data: {
theme: this.theme,
sidebarCollapsed: this.sidebarCollapsed,
density: this.density,
identity: this.identity,
},
}
localStorage.setItem(STORAGE_KEY, JSON.stringify(payload))
},
clearSessionIdentity() {
this.identity = null
this.persist()
},
clearAllPersistedState() {
localStorage.removeItem(STORAGE_KEY)
this.$reset()
},
},
})这是项目模块示例,依赖已安装的 Pinia,并由应用入口调用 hydrate()。当偏好变化时调用 persist();退出登录时调用 clearSessionIdentity(),保留与账号无关的主题和布局偏好。
接入应用并验证
在创建 Pinia 后恢复缓存,再挂载应用,能够避免页面先按默认主题渲染、随后突然切换。主题或布局发生变化时再主动保存,不要对整个 Store 做无限频率的深度监听。
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import { useAppPreferencesStore } from './stores/appPreferences'
const app = createApp(App)
const pinia = createPinia()
app.use(pinia)
const preferencesStore = useAppPreferencesStore(pinia)
preferencesStore.hydrate()
app.mount('#app')生效行为:刷新页面后,未过期且版本可识别的主题、侧栏和密度设置会恢复;损坏、过期或无法迁移的缓存会被删除并回退到默认值。启动开发服务器进行验证:
npm run dev预期输出:
VITE ready in <TIME> ms
Local: http://localhost:<PORT>/实际启动时间和端口可能不同。修改主题后刷新页面,应保持当前主题;手动把缓存中的 expiresAt 改成过去时间,再刷新页面,应恢复默认设置并删除旧缓存。
处理升级、退出与多标签页
缓存结构发生不兼容变化时应提升版本号,并在 migrate() 中显式迁移。无法确认语义的旧数据不要强行复用,直接失效比错误恢复更安全。
退出登录必须清理持久化身份副本和对应内存状态,但可以保留与账号无关的主题、密度与布局偏好。若后台允许同一账号在多个标签页使用,还可以监听 storage 事件:其他标签页清除身份时,当前标签页同步执行退出或重新拉取会话。
缓存只负责改善体验,不能作为身份真实性、权限有效性或业务数据正确性的依据。所有安全判断仍应由服务端完成。