服务端渲染 (SSR)

通过 Pinia 作者的官方视频课程掌握更多内容

TIP

如果你使用的是 Nuxt，你需要阅读的是这些说明文档。

只要你只在 setup 函数、getter 和 action 的顶部调用你定义的 useStore() 函数，那么使用 Pinia 创建 store 对于 SSR 来说应该是开箱即用的：

<script setup>
// 这是可行的，
// 因为 pinia 知道在 `setup` 中运行的是什么程序。
const main = useMainStore()
</script>

在 setup() 外部使用 store

如果你需要在其他地方使用 store，你需要将原本被传递给应用的 pinia 实例传递给 useStore() 函数：

const pinia = createPinia()
const app = createApp(App)

app.use(router)
app.use(pinia)

router.beforeEach((to) => {
  // ✅ 这会正常工作，因为它确保了正确的 store 被用于
  // 当前正在运行的应用
  const main = useMainStore(pinia)

  if (to.meta.requiresAuth && !main.isLoggedIn) return '/login'
})

Pinia 会将自己作为 $pinia 添加到你的应用中，所以你可以在 serverPrefetch() 等函数中使用它：

export default {
  serverPrefetch() {
    const store = useStore(this.$pinia)
  },
}

注意，在使用 onServerPrefetch() 时，你不需要做任何特别的事情：

<script setup>
const store = useStore()
onServerPrefetch(async () => {
  // ✅ 这会正常工作
  await store.fetchData()
})
</script>

State 激活

为了激活初始 state，你需要确保 rootState 包含在 HTML 中的某个地方，以便 Pinia 稍后能够接收到它。根据你服务端所渲染的内容，为了安全你应该转义 state。我们推荐 Nuxt 使用的 devalue：

import devalue from 'devalue'
import { createPinia } from 'pinia'
// 检索服务端的 rootState
const pinia = createPinia()
const app = createApp(App)
app.use(router)
app.use(pinia)

// 渲染页面后，rootState 被建立，
// 可以直接在 `pinia.state.value`上读取。

// 序列化，转义(如果 state 的内容可以被用户改变，这点就非常重要，几乎都是这样的)
// 并将其放置在页面的某处
// 例如，作为一个全局变量。
devalue(pinia.state.value)

根据你服务端所渲染的内容，你将设置一个初始状态变量，该变量将在 HTML 中被序列化。你还应该保护自己免受 XSS 攻击。你可以根据你的需要使用 devalue 的其他替代品，例如，如果你可以用 JSON.stringify()/JSON.parse() 来序列化和解析你的 state，你可以把性能提高很多。

如果你没有使用 Nuxt，你需要自己处理 state 的序列化和激活。这里有一些例子：

• Vitesse 模板
• vite-plugin-ssr

根据你的环境调整这个策略。确保在客户端调用任何 useStore() 函数之前，激活 pinia 的 state。例如，如果我们将 state 序列化为一个 <script> 标签，并在客户端通过 window.__pinia 全局访问它，我们可以这样写：

const pinia = createPinia()
const app = createApp(App)
app.use(pinia)

// `isClient` 取决于环境，例如在 Nuxt 中它是 `import.meta.client`
if (isClient) {
  pinia.state.value = JSON.parse(window.__pinia)
}