Vue 3 的 ref 需手动桥接 localStorage 实现双向同步：单页内通过 watchEffect 写入、onMounted 读取；跨页需监听 storage 事件更新 ref；推荐封装为 useLocalStorage 组合式函数。
Vue 3 的 ref 本身不自动关联 localStorage，要实现数据同步，关键在于“手动桥接”：用 ref 管理响应式状态，再通过读写 localStorage + 监听 storage 事件，让多个标签页间的状态保持一致。核心不是让 ref “变成本地存储”，而是让它和 localStorage 双向可控联动。
基础同步：单页内 ref ↔ localStorage
适合主题色、折叠状态、表单草稿等轻量状态。只需三步：
- 初始化 ref 时从 localStorage 读取值（支持 fallback）
- 用
watchEffect或watch监听 ref 变化，自动写入 localStorage - 确保首次加载就还原状态（避免闪动或丢失）
示例：
import { ref, watchEffect, onMounted } from 'vue'
const theme = ref(localStorage.getItem('theme') || 'light')
onMounted(() => {
const saved = localStorage.getItem('theme')
if (saved !== null) theme.value = saved
})
watchEffect(() => {
localStorage.setItem('theme', theme.value)
})
跨标签页同步：加 storage 事件监听
localStorage 修改不会触发当前页的 storage 事件，所以仅靠 watchEffect 不够。必须额外监听全局 storage 事件，把其他标签页的变更“拉回来”并更新 ref：
立即学习“前端免费学习笔记（深入）”；
蓝湖代码转vue2.0+element-ui
下载
将静态 Vue 页面(index.vue)改造为动态页面(Custom.vue)；稿源仅限 index.vue、其引用的 CSS 与资源路径，禁止参考仓库内其他文件。Invoke when user wants to transform a static Vue page into a dynamic data-driven page with Element UI components.
- 统一写入逻辑：所有修改都走封装函数（如
setTheme(val)），先改 ref 再存 localStorage - 在 setup 或 onBeforeMount 中注册一次
window.addEventListener('storage') - 事件回调里判断 key 匹配，再解析
event.newValue并赋值给 ref - 注意守卫：避免 newValue 为 null 或与当前值相同，防止无意义更新
示例片段：
watchEffect(() => {
localStorage.setItem('theme', theme.value)
})
window.addEventListener('storage', (e) => {
if (e.key === 'theme' && e.newValue !== null) {
theme.value = e.newValue
}
})
进阶封装：用 customRef 或组合式函数
重复写监听/读写逻辑容易出错。推荐封装成可复用的工具：
-
customRef：完全控制 get/set，适合防抖、验证、自动序列化等场景（如只允许存字符串或 JSON 对象） -
useLocalStorage组合式函数：接收 key 和默认值，内部处理读取、写入、监听、清理，返回一个响应式 ref - 类型安全：用
JSON.parse/JSON.stringify时注意值必须可序列化；建议限制为 string / number / boolean / plain object
简单封装示意：
function useLocalStorage(key, initialValue) {
const storedValue = localStorage.getItem(key)
const value = ref(storedValue ?? initialValue)
watchEffect(() => {
localStorage.setItem(key, value.value)
})
window.addEventListener('storage', (e) => {
if (e.key === key && e.newValue !== null) {
value.value = e.newValue
}
})
return value
}
避坑要点
几个容易忽略但影响稳定性的细节：
- 不要在
watchEffect外直接读 localStorage 赋值给 ref —— 这样无法响应后续其他标签页的变更 - storage 事件不触发当前页自身修改，所以写入后必须主动更新 ref（即“劫持”写操作）
- 高频写入（如输入框实时存）会阻塞主线程，建议加防抖或只存关键时机（如失焦、提交）
- 多组件共用同一 key 时，确保语义一致；避免不同组件各自 setItem 导致覆盖冲突
