Pinia 中 SSR 环境下 readonly ref 的 hydration 问题解析

问题背景

在 Pinia 状态管理库中，当开发者尝试在服务端渲染(SSR)环境下使用 readonly 包装的 ref 返回值时，会遇到控制台警告："Set operation on key 'value' failed: target is readonly"。这个问题涉及到 Pinia 在 SSR 环境下的 hydration(水合)机制。

技术原理分析

readonly 的本质

readonly 是 Vue 提供的一个 API，它会创建一个代理对象，该对象会阻止对原始响应式对象的直接修改。从技术实现上看，readonly 与 computed 类似，都是基于原始响应式对象的派生状态。

SSR 的 hydration 过程

在服务端渲染中，Pinia 会将初始状态序列化并嵌入到 HTML 中。当客户端应用启动时，Pinia 会将这些状态重新"水合"到客户端的 store 中。这个过程要求状态必须是可写的，因为：

1. 需要将服务端的状态精确地恢复到客户端
2. 需要确保服务端和客户端的状态一致性
3. 水合过程本身需要对状态进行写入操作

问题根源

当开发者使用 readonly 包装 ref 时，Pinia 在 hydration 阶段尝试写入这些属性，但由于它们被标记为只读，Vue 会抛出警告。这与 Pinia 的设计原则相冲突：

• 状态必须是可写的以确保 hydration 能正常工作
• 派生状态(如 computed)会被自动跳过 hydration
• readonly 被视为一种状态而非派生状态

解决方案

根据 Pinia 核心团队的说明，正确的做法是：

1. 避免在 store 中使用 readonly：状态应该是可写的，这是 Pinia 的设计原则
2. 使用 computed 替代：如果需要派生只读状态，使用 computed 更符合预期
3. 显式跳过 hydration：如果确实需要 readonly，可以使用 skipHydrate 辅助函数

export const useAuthStore = defineStore('auth', () => {
  const foo = ref('foo')

  return {
    // 推荐做法：使用 computed
    bar: computed(() => foo.value),
    
    // 替代方案：显式跳过 hydration
    baz: skipHydrate(readonly(foo))
  }
})

最佳实践建议

1. 区分状态和派生状态：将可写状态和只读派生状态明确分开
2. 优先使用 computed：对于只读数据，computed 是更自然的选择
3. 理解 SSR 的限制：在服务端渲染环境下，状态管理需要特殊考虑
4. 遵循 Pinia 的设计哲学：状态应该是可写的，派生状态应该是只读的

总结

Pinia 在 SSR 环境下对 readonly ref 的处理是一个有意为之的设计选择，旨在确保 hydration 过程的可靠性和一致性。开发者应该理解状态可写性在 SSR 中的重要性，并遵循 Pinia 推荐的模式来组织 store 中的状态。通过使用 computed 或显式跳过 hydration，可以既保持代码的清晰性，又避免运行时警告。