Pinia 在 Nuxt 3/4 中的集成与实践:SSR 状态管理的完整指南

原创2026-09-21 17:37:162,180 阅读
文章标签:前端状态管理

Pinia 在 Nuxt 3/4 中的集成与实践:SSR 状态管理的完整指南

本篇技术指南以 Pinia 官方文档《Nuxt》章节(packages/docs/ssr/nuxt.md)为骨架,系统讲解如何在 Nuxt 3 与 Nuxt 4 项目中安装、注册、使用 Pinia,涵盖 callOnce 数据预取、stores 目录自动导入、storesDirs 自定义配置,并结合当前仓库中 @pinia/nuxt 模块的源码(packages/nuxt/src/module.ts)与端到端测试(packages/nuxt/test/nuxt.spec.ts)深入剖析其 SSR 序列化、状态水合与 HMR 的底层实现。读完本文,你将能够把 Pinia 无缝接入 Nuxt 项目,正确地在服务端预取数据并完成客户端水合,同时掌握避免重复请求、防止 XSS 注入和自定义 store 自动导入路径的完整实战方案。

Nuxt 让 Pinia 的 SSR 变得简单

在纯 Vue SSR 场景中,使用 Pinia 需要开发者自己处理状态序列化、XSS 转义与客户端水合等一系列问题(详见 packages/docs/ssr/index.md)。而将 Pinia 与 Nuxt 搭配使用时,情况要简单得多:Nuxt 本身接管了服务端渲染中的大量工作,例如你完全不需要关心状态序列化(serialization)与 XSS 攻击防护——这两件事由 @pinia/nuxt 模块内置完成。

Pinia 官方支持 Nuxt 3 和 Nuxt 4。从模块源码的兼容性声明可以看到(packages/nuxt/src/module.ts#L29-L36):

compatibility: {
  nuxt: '^3.15.0 || ^4.0.0 || ^5.0.0',
},

即该模块兼容 Nuxt 3.15 及以上、Nuxt 4 以及 Nuxt 5 的版本范围。

安装与注册

方式一:使用 nuxi 自动安装(推荐)

在项目根目录执行以下命令:

npx nuxi@latest module add pinia

该命令会同时向项目添加 @pinia/nuxt 和 pinia 两个依赖。如果安装后发现 pinia 没有被自动安装,请使用你的包管理器手动安装:

npm i pinia @vue/devtools-api

注意:自 Pinia v4 起,@vue/devtools-api 是 pinia 的必需 peer dependency(对等依赖),必须显式安装,否则依赖解析会失败。

方式二:手动安装

手动安装方式与 @pinia/nuxt 的 README(packages/nuxt/README.md)中描述一致:

npm i pinia @pinia/nuxt

解决 npm 的 ERESOLVE 错误

如果你使用 npm,可能会遇到 ERESOLVE unable to resolve dependency tree(无法解析依赖树)错误。此时需要在 package.json 中添加如下 overrides 配置:

"overrides": {
  "vue": "latest"
}

注册模块

模块会替你处理所有事情(创建 Pinia 实例、注入 $pinia、注册水合插件等),你只需要在 nuxt.config 文件中把它加入 modules 数组:

// nuxt.config.js
export default defineNuxtConfig({
  // ... other options
  modules: [
    // ...
    '@pinia/nuxt',
  ],
})

这就完成了!接下来照常使用你的 store 即可。以仓库中的 playground 为例(packages/nuxt/playground/nuxt.config.ts),它直接引用了本地模块源码并配置了自定义 stores 目录:

import piniaModule from '../src/module'

export default defineNuxtConfig({
  modules: [piniaModule],
  pinia: {
    storesDirs: ['./stores/**', './domain/*/stores'],
  },
  compatibilityDate: '2024-09-26',
})

在页面中等待 actions 执行完成

服务端渲染时,往往需要在页面渲染前完成数据预取。与 onServerPrefetch() 类似,你可以在 Nuxt 的 callOnce() 组合式函数中调用 store 的 action。callOnce 保证该 action 只执行一次,从而避免重复拉取已经存在于 store 中的数据:

<script setup>
const store = useStore()
// 我们也可以把数据解构出来,但它已经存在于 store 中了
await callOnce('user', () => store.fetchUser())
</script>

callOnce() 的第二个参数是唯一标识 key(这里是 'user'),用于确保同一个 key 的调用在整次渲染周期中只运行一次。

根据你的需求,你可以选择只在客户端运行一次该 action,或者在每次导航时都运行(后者更接近 useFetch() / useAsyncData() 的数据获取行为):

<script setup>
const store = useStore()
await callOnce('user', () => store.fetchUser(), { mode: 'navigation' })
</script>

mode: 'navigation' 让回调在每次客户端导航时重新执行,而默认模式('once')则在整个会话内只执行一次。

在 setup() 之外使用 store:显式传入 pinia 实例

如果你需要在 setup() 或"注入感知"(injection aware)上下文之外使用 store——例如 Navigation guards(导航守卫)、其他 store、Nuxt Middlewares(中间件)等——请记住要把 pinia 实例传给 useStore(),原因详见 packages/docs/core-concepts/outside-component-usage.md 中关于 SSR 应用的说明。获取 pinia 实例的方式因环境而异:

import { useStore } from '~/stores/myStore'

// 这一行通常位于一个能够获取 pinia 实例的函数内部
const store = useStore(pinia)

好在大多数时候你并不需要经历这些麻烦——只要在 setup、getters、actions 的顶层调用 useStore(),Pinia 会自动识别当前正在运行的应用程序并返回正确的 store。

在 Nuxt 环境中,获取 pinia 实例最简单的方式就是模块提供的 usePinia()(见下文"自动导入"一节),其实现为 useNuxtApp().$pinia。

自动导入(Auto imports)

默认情况下,@pinia/nuxt 会暴露以下自动导入:

import { useNuxtApp } from '#app'
import type { Pinia } from 'pinia'
export * from 'pinia'

export const usePinia = () => useNuxtApp().$pinia as Pinia

可以看到,usePinia() 实际上就是从 Nuxt 应用上下文中取出 $pinia 并断言为 Pinia 类型;同时该文件将 pinia 的全部导出(export * from 'pinia')一并转发,使得 defineStore 等 API 在 Nuxt 中也能自动导入。

这些自动导入在模块的 setup 中通过 addImports 逐一注册(packages/nuxt/src/module.ts#L64-L71):

const composables = resolve(runtimeDir, 'composables')
addImports([
  { from: composables, name: 'defineStore' },
  { from: composables, name: 'acceptHMRUpdate' },
  { from: composables, name: 'usePinia' },
  { from: composables, name: 'storeToRefs' },
])

stores 目录的自动导入

模块还会自动导入 stores 文件夹(Nuxt 4 中为 app/stores)中定义的所有 store。不过它不会递归查找嵌套目录中的 store。默认目录解析逻辑位于 packages/nuxt/src/module.ts#L73-L86:

if (!options.storesDirs) {
  // 默认相对 srcDir(默认为项目根目录)解析
  options.storesDirs = [resolve(nuxt.options.srcDir, 'stores')]
}

if (options.storesDirs) {
  const layers = getLayerDirectories(nuxt)
  for (const storeDir of options.storesDirs) {
    for (const layer of layers) {
      addImportsDir(resolve(layer.app, storeDir))
    }
  }
}

从源码可以看出两点关键行为:

  1. 默认目录是 srcDir/stores,即项目根目录下的 stores(Nuxt 4 新目录结构中为 app/stores);
  2. 模块通过 getLayerDirectories(nuxt) 获取所有 Nuxt layers,并对每个 layer 都执行 addImportsDir——这意味着 Nuxt layers 中的 stores 也能被自动导入,这一点由测试 packages/nuxt/test/nuxt.spec.ts#L37-L39 验证(断言页面包含 Layer store: 0)。

自定义 storesDirs

你可以通过 storesDirs 选项自定义自动导入的目录,包括启用嵌套 store 的自动导入:

// nuxt.config.ts
export default defineNuxtConfig({
  // ... other options
  modules: ['@pinia/nuxt'],
  pinia: {
    storesDirs: ['./stores/**', './custom-folder/stores/**'],
  },
})

注意:

  • 目录路径相对于项目根目录;
  • 如果你修改了 srcDir 选项,需要相应调整这些路径;
  • 想要导入嵌套 store,可以使用 glob 模式:Nuxt 3 用 stores/**,Nuxt 4+ 用 app/stores/**(见 packages/nuxt/src/module.ts#L17-L27 中 ModuleOptions 的 JSDoc 注释);
  • 该项的作用与直接配置 Nuxt 的 imports.dirs 相同。

仓库的 playground 页面 packages/nuxt/playground/pages/index.vue 演示了这些自动导入的实际效果——它不写任何 import 语句就直接使用了顶层 store、嵌套 store(~/stores/nested/some-stores.ts)、domain 目录 store(~/domain/one/stores/testStore.ts)以及 layer 中的 store:

<script lang="ts" setup>
const counter = useCounter()

useTestStore() // ~/domain/one/stores/testStore.ts
useSomeStoreStore() // ~/stores/nested/some-stores.ts
const layerStore = useBasicStore() // ~~/layers/layer-domain/stores/basic.ts

if (import.meta.server) {
  counter.increment()
}
</script>

源码级解析:模块在 SSR 中做了什么

理解了使用方法后,我们再深入 @pinia/nuxt 的源码,看看这个"模块替你处理一切"究竟处理了什么。

运行时插件:创建 Pinia 并完成状态水合

模块在 modules:done 钩子中注册了两个运行时插件——plugin 与 payload-plugin(packages/nuxt/src/module.ts#L57-L62)。其中核心的 plugin(packages/nuxt/src/runtime/plugin.ts)完整代码为:

const plugin: Plugin<{ pinia: Pinia }> = defineNuxtPlugin({
  name: 'pinia',
  setup(nuxtApp) {
    const pinia = createPinia()
    nuxtApp.vueApp.use(pinia)
    setActivePinia(pinia)

    if (nuxtApp.payload && nuxtApp.payload.pinia) {
      pinia.state.value = nuxtApp.payload.pinia as any
    }

    // 注入 $pinia
    return {
      provide: {
        pinia,
      },
    }
  },
  hooks: {
    'app:rendered'() {
      const nuxtApp = useNuxtApp()
      nuxtApp.payload.pinia = toRaw(nuxtApp.$pinia as Pinia).state.value
      // 在服务端清除对 pinia 的引用,避免持有变量不释放
      setActivePinia(undefined)
    },
  },
})

它完成了 SSR 中最关键的三件事:

  1. 创建并激活 Pinia:createPinia() 后通过 vueApp.use(pinia) 注入 Vue 应用,并调用 setActivePinia(pinia) 设置全局激活实例;
  2. 客户端水合:在 setup 阶段,如果 Nuxt 的 payload 中带有 pinia 字段,则直接将其还原为 pinia.state.value——这正是服务端渲染出的状态在客户端被"拾回"的过程;
  3. 服务端序列化:在 app:rendered 钩子(服务端渲染完成)中,把当前 pinia.state.value 写入 nuxtApp.payload.pinia,随 HTML payload 一同发送给客户端;随后调用 setActivePinia(undefined) 清除服务端的全局引用,避免跨请求污染与内存残留。

跳过水合:skipHydrate 的 payload 优化

模块还注册了一个 payload-plugin(packages/nuxt/src/runtime/payload-plugin.ts),用于在序列化时剔除被 skipHydrate() 标记的状态,避免把无用的数据发送到客户端:

const payloadPlugin = definePayloadPlugin(() => {
  definePayloadReducer(
    'skipHydrate',
    // 需要返回一个真值才会被当作匹配
    (data: unknown) => !shouldHydrate(data) && 1
  )
  definePayloadReviver('skipHydrate', (_data: 1) => undefined)
})

它通过 definePayloadReducer 拦截"不需要水合"的数据(返回 1 表示命中),并用 definePayloadReviver 在客户端还原为 undefined。playground 中的 packages/nuxt/playground/stores/with-skip-hydrate.ts 展示了 skipHydrate 的用法:

import { skipHydrate } from 'pinia'

export const useWithSkipHydrateStore = defineStore('with-skip-hydrate', () => {
  const skipped = skipHydrate(
    ref({
      text: 'I should not be serialized or hydrated',
    })
  )
  return { skipped }
})

对应的端到端测试 packages/nuxt/test/nuxt.spec.ts#L31-L35 断言:服务端返回的 HTML 中不包含 I should not be serialized or hydrated 这段标记跳过的文本,但页面仍能正确渲染(包含 skipHydrate-wrapped state is correct)。

开发模式下的自动 HMR 注册

在开发模式下(nuxt.options.dev),模块会额外注册一个 Vite 插件(packages/nuxt/src/auto-hmr-plugin.ts),自动为每个使用 defineStore 定义 store 的文件注入 HMR 代码:

return {
  code: [
    `import { acceptHMRUpdate } from 'pinia'`,
    code,
    'if (import.meta.hot) {',
    `  import.meta.hot.accept(acceptHMRUpdate(${storeName}, import.meta.hot))`,
    '}',
  ].join('\n'),
}

该插件通过解析 AST 查找顶层 defineStore(...) 声明(支持 VariableDeclaration 与 ExportNamedDeclaration),找到后自动追加 import.meta.hot.accept(acceptHMRUpdate(storeName, import.meta.hot)),这样你修改 store 时无需手动编写 HMR 代码,页面热更新也不会丢失状态。这正是原文档中自动导入 acceptHMRUpdate() 的深层意义——即便你需要手动处理 HMR,该 API 也已就绪。

其他模块级细节

测试验证:模块开箱即用

仓库自带的端到端测试(packages/nuxt/test/nuxt.spec.ts)覆盖了模块的核心能力:

it('works on ssr', async () => {
  const html = await $fetch('/')
  expect(html).toContain('Count: 101')
})

it('drops state that is marked with skipHydrate', async () => {
  const html = await $fetch('/skip-hydrate')
  expect(html).not.toContain('I should not be serialized or hydrated')
  expect(html).toContain('skipHydrate-wrapped state is correct')
})

it('can auto import from layers', async () => {
  expect(await $fetch('/')).toContain('Layer store: 0')
})

三个测试分别验证了:

  1. SSR 渲染正常:页面中的 counter store 初始 count: 100,在服务端执行 increment() 后渲染出 Count: 101(对应 packages/nuxt/playground/stores/counter.ts 中 state 为 100、页面在 import.meta.server 下调用 increment());
  2. skipHydrate 生效:被标记的状态不会出现在服务端返回的 HTML 中,但客户端状态仍然正确(对应 packages/nuxt/playground/pages/skip-hydrate.vue);
  3. layers 中的 store 自动导入:Nuxt layers 目录下定义的 store 可以被自动导入并使用。

与通用 SSR 方案的对比

如果你不使用 Nuxt,则需要自行处理状态序列化与 XSS 防护:在服务端渲染完成后读取 pinia.state.value,用 devalue 这类工具序列化并转义后嵌入 HTML,客户端在调用任何 useStore() 之前将初始状态写回 pinia.state.value(详见 packages/docs/ssr/index.md 的 State hydration 章节)。而使用 @pinia/nuxt 时,上述全部流程由插件自动完成,无需任何手写代码——这正是原文档开头"你不需要关心序列化与 XSS 攻击"这句话的完整含义。

小结

将 Pinia 接入 Nuxt 的完整流程可以概括为三步:npx nuxi@latest module add pinia 安装(或手动 npm i pinia @pinia/nuxt)→ 在 nuxt.config 的 modules 中注册 @pinia/nuxt → 把 store 放入 stores(Nuxt 4 为 app/stores)目录即享自动导入。在此基础上,你可以通过 callOnce() 在服务端预取数据、通过 storesDirs 扩展 store 扫描目录,而序列化、水合、XSS 防护与 HMR 注册等细节全部由模块在 packages/nuxt/src/module.ts、packages/nuxt/src/runtime/plugin.ts 与 packages/nuxt/src/runtime/payload-plugin.ts 中透明处理。若想深入验证这些行为,仓库的 packages/nuxt/playground 目录与 packages/nuxt/test/nuxt.spec.ts 是绝佳的参考样例。

登录后查看全文
pinia