Pinia 在 Nuxt 3/4 中的集成与实践:SSR 状态管理的完整指南
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 会暴露以下自动导入:
usePinia():与getActivePinia()类似,但与 Nuxt 配合得更好。其实现(packages/nuxt/src/runtime/composables.ts)如下:
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 中也能自动导入。
defineStore():用于定义 storestoreToRefs():需要从 store 中解构出单个 ref 时使用acceptHMRUpdate():用于热模块替换(HMR),详见 packages/docs/cookbook/hot-module-replacement.md
这些自动导入在模块的 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))
}
}
}
从源码可以看出两点关键行为:
- 默认目录是
srcDir/stores,即项目根目录下的stores(Nuxt 4 新目录结构中为app/stores); - 模块通过
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 中最关键的三件事:
- 创建并激活 Pinia:
createPinia()后通过vueApp.use(pinia)注入 Vue 应用,并调用setActivePinia(pinia)设置全局激活实例; - 客户端水合:在
setup阶段,如果 Nuxt 的 payload 中带有pinia字段,则直接将其还原为pinia.state.value——这正是服务端渲染出的状态在客户端被"拾回"的过程; - 服务端序列化:在
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 也已就绪。
其他模块级细节
- 避免多份 pinia 副本:模块将
pinia加入 Vite 的optimizeDeps.exclude(packages/nuxt/src/module.ts#L46-L51),确保整个应用中只有一个 pinia 实例; - 类型支持:模块通过
prepare:types钩子注入@pinia/nuxt的类型引用,让自动导入具备完整的类型提示(packages/nuxt/src/module.ts#L53-L55)。
测试验证:模块开箱即用
仓库自带的端到端测试(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')
})
三个测试分别验证了:
- SSR 渲染正常:页面中的 counter store 初始
count: 100,在服务端执行increment()后渲染出Count: 101(对应 packages/nuxt/playground/stores/counter.ts 中 state 为 100、页面在import.meta.server下调用increment()); - skipHydrate 生效:被标记的状态不会出现在服务端返回的 HTML 中,但客户端状态仍然正确(对应 packages/nuxt/playground/pages/skip-hydrate.vue);
- 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 是绝佳的参考样例。