Nuxt v3页面刷新状态持久化方案咨询及代码问题排查

现有代码问题分析 #

你当前的实现存在两个核心问题：

1. Hydration 不匹配：useState 的工厂函数在服务端和客户端都会执行，服务端返回 null，但客户端直接读取 localStorage 返回用户数据，导致服务端渲染的初始状态与客户端不一致，Nuxt 会触发 hydration mismatch 并重置状态为服务端的 null，所以看起来持久化失效。
2. 状态未同步更新：没有监听 user 状态的变化，当用户信息更新时，不会自动同步到 localStorage，刷新后无法获取最新状态。

修正后的实现代码 #

修改 composables/states.ts 如下：

export const useUser = () => {
  // 初始化时服务端和客户端返回相同的初始值，避免 hydration 不匹配
  const user = useState<User | null>('user', () => null)

  if (process.client) {
    // 客户端挂载完成后再从 localStorage 恢复状态，此时 hydration 已完成
    onMounted(() => {
      const savedUser = localStorage.getItem('user')
      if (savedUser) {
        try {
          const parsedUser: User = JSON.parse(savedUser)
          // 验证过期时间
          if (new Date(parsedUser.expires) > new Date()) {
            user.value = parsedUser
          } else {
            // 清理过期数据
            localStorage.removeItem('user')
          }
        } catch (error) {
          // 解析失败时清理无效数据
          localStorage.removeItem('user')
        }
      }
    })

    // 监听状态变化，实时同步到 localStorage
    watch(user, (newUser) => {
      if (newUser) {
        // 注意：将 Date 对象转为 ISO 字符串存储，避免序列化问题
        localStorage.setItem('user', JSON.stringify({
          ...newUser,
          expires: newUser.expires instanceof Date ? newUser.expires.toISOString() : newUser.expires
        }))
      } else {
        localStorage.removeItem('user')
      }
    }, { deep: true })
  }

  return user
}

// 调整 expires 类型为 string，适配 JSON 序列化后的格式
export type User = {
  email: string
  username: string
  name: string
  zipCode: string
  profilePicture: string
  expires: string
}

关键优化点说明 #

• 避免 Hydration Mismatch：

  • 初始化 useState 时，服务端和客户端统一返回 null，保证初始状态一致。
  • 仅在客户端 onMounted 钩子中读取 localStorage，此时组件已完成 hydration，不会触发状态不匹配。

• 状态持久化同步：

  • 使用 watch 监听 user 状态的变化（开启 deep: true 监听对象内部属性），实时将最新状态写入 localStorage。

• 数据可靠性处理：

  • 解析 localStorage 数据时捕获异常，避免无效数据导致页面报错。
  • 验证过期时间，自动清理过期的用户数据。
  • 将 Date 对象转为 ISO 字符串存储，解决 JSON 序列化/反序列化的类型问题。

其他可选方案 #

如果你的用户信息需要在服务端也能访问（比如用于 SSR 渲染用户相关内容），可以改用 useCookie 替代 localStorage：

• Cookie 会随每次请求发送到服务端，服务端可以直接读取。
• 但 Cookie 有大小限制（约 4KB），适合存储精简的用户标识或核心信息。

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