watchEffect 无法监听 localStorage 变化,因其非 Vue 响应式数据;需用 storage 事件捕获跨标签页修改,并通过 ref 代理实现响应式同步。

watchEffect 本身无法直接监听 LocalStorage 的变化,因为 LocalStorage 的修改不会触发 Vue 响应式系统。要实现多标签页同步,需结合 storage 事件 + 响应式状态 + watchEffect 主动追踪。
为什么 watchEffect 看不到 LocalStorage 变化
watchEffect 只响应 Vue 的响应式数据(ref、reactive 等)。localStorage 是浏览器全局 API,写入时既不改变响应式变量,也不派发事件给 Vue,所以单纯把 localStorage.getItem() 写在 watchEffect 里——它只在首次执行时读取一次,后续 localStorage 被其他标签页修改,watchEffect 完全无感。
正确做法:用 storage 事件 + 响应式代理
核心思路:把 localStorage 封装成一个响应式“代理”,所有读写都经过它;当其他标签页修改 localStorage 时,当前页通过 window.addEventListener('storage') 捕获事件,并手动更新这个响应式变量,从而触发 watchEffect 重新运行。
- 定义一个 ref 存储实际值(如 const theme = ref(localStorage.getItem('theme') || 'light'))
- 封装 setItem 方法:先更新 ref,再调用 localStorage.setItem,确保本地状态和存储一致
- 监听 storage 事件:当同域下其他标签页修改该 key,当前页收到事件后,用 localStorage.getItem 重新读取并更新 ref
- 在 watchEffect 中直接使用该 ref —— 它现在是真正响应式的
完整示例(组合式 API)
(Vue 3 + TypeScript)
import { ref, watchEffect, onMounted, onUnmounted } from 'vue'
export function useLocalStorage(key, initialValue) {
const data = ref(initialValue)
// 初始化:从 localStorage 读取
const init = () => {
const saved = localStorage.getItem(key)
if (saved !== null) {
try {
data.value = JSON.parse(saved)
} catch {
data.value = saved
}
}
}
// 写入:同步更新 ref 和 localStorage
const setItem = (value) => {
data.value = value
try {
localStorage.setItem(key, JSON.stringify(value))
} catch {
localStorage.setItem(key, String(value))
}
}
// 监听其他标签页的修改
const handleStorage = (e) => {
if (e.key === key) {
init()
}
}
onMounted(() => {
init()
window.addEventListener('storage', handleStorage)
})
onUnmounted(() => {
window.removeEventListener('storage', handleStorage)
})
return {
data,
setItem
}
}
// 在组件中使用
export default {
setup() {
const { data: theme, setItem: setTheme } = useLocalStorage('theme', 'light')
watchEffect(() => {
console.log('主题已切换为:', theme.value)
document.documentElement.setAttribute('data-theme', theme.value)
})
return { theme, setTheme }
}
}
注意事项与增强点
- storage 事件只在其他标签页修改时触发,本页调用 localStorage.setItem 不会触发自身监听 —— 所以必须手动同步 ref(如上例中的 setItem)
- 事件对象 e.newValue 是字符串,null 表示被 clear 或 remove,注意判空处理
- 避免高频触发:如果多个 key 共享同一套逻辑,可用 Map 缓存 handler,统一管理
- 服务端渲染(SSR)场景下 localStorage 不存在,需加 typeof window !== 'undefined' 判断










