在 Nuxt 中集成 Pinia:SSR 友好的状态管理完整指南
在 Nuxt 中集成 Pinia:SSR 友好的状态管理完整指南
导读
本文聚焦 Pinia 与 Nuxt(含 Nuxt 3/4)的官方集成方案 @pinia/nuxt,系统讲解从安装、模块配置到在 asyncData/callOnce/useAsyncData 中使用 store、自动引入与自定义 storesDirs、SSR 状态序列化与 skipHydrate、以及 HMR 与 Nuxt 2 兼容等完整实战要点。读完本文,你将掌握在 Nuxt 应用中零手动序列化、零 XSS 顾虑地使用 Pinia 状态,并能结合源码理解其底层工作原理。
为什么在 Nuxt 中使用 Pinia 更简单
Pinia 是一个基于 Vue Composition API 的直观、类型安全、轻量且灵活的状态库。而在 Nuxt 中,@pinia/nuxt 模块进一步消除了**服务器端渲染(SSR)**的大部分心智负担:
- 无需关心序列化:Nuxt 模块内置的 payload 插件会在服务端渲染结束时自动把 Pinia 状态写入
nuxtApp.payload,客户端激活时再自动恢复(详见下文源码分析)。 - 无需担心 XSS 攻击:状态在服务端与客户端之间通过 Nuxt 的 payload 机制传递,由 Nuxt 负责安全的序列化/反序列化。
- 开箱即用的集成:Pinia 支持 Nuxt 3、Nuxt 4(以及通过
@nuxtjs/composition-api支持纯 Nuxt 2,见下文)。
@pinia/nuxt 模块的运行时行为由 packages/nuxt/src/runtime/plugin.ts 定义:它在 createPinia() 后调用 nuxtApp.vueApp.use(pinia) 注册到 Vue 应用,并执行 setActivePinia(pinia) 设置全局活动实例,同时通过 provide 注入 $pinia,供 usePinia() 等组合式函数在 Nuxt 应用中随时取用。
安装与快速上手
方式一:使用 nuxi 自动安装(推荐)
Nuxt 3/4 官方推荐直接使用 nuxi 的模块添加命令:
npx nuxi@latest module add pinia
该命令会自动把 @pinia/nuxt 与 pinia 一同写入项目依赖并注册到 nuxt.config.ts。如果发现 pinia 没有被安装,请手动补充:
npm i pinia @vue/devtools-api
注意:自 pinia v4 起,
@vue/devtools-api是pinia的必选 peer 依赖(见 packages/pinia/package.json),必须保证其已安装。
方式二:手动安装
yarn add pinia @pinia/nuxt @vue/devtools-api
# 或者使用 npm
npm install pinia @pinia/nuxt @vue/devtools-api
可能遇到的 npm 依赖冲突
如果你正在使用 npm,可能会遇到 ERESOLVE unable to resolve dependency tree 错误。此时在 package.json 中添加 overrides 即可:
"overrides": {
"vue": "latest"
}
在 nuxt.config 中注册模块
@pinia/nuxt 是一个 Nuxt module,只需把它加入 modules 数组即可:
// nuxt.config.js
export default defineNuxtConfig({
// ... 其他配置
modules: [
// ...
'@pinia/nuxt',
],
})
模块源码位于 packages/nuxt/src/module.ts,其 compatibility 声明为 nuxt: '^3.15.0 || ^4.0.0 || ^5.0.0',即官方支持 Nuxt 3.15+ 与 Nuxt 4/5。模块初始化时还会做两件关键事情:
- 把 runtime 目录加入
build.transpile,并让 Vite 的optimizeDeps.exclude排除pinia,避免项目中出现多份 Pinia 副本; - 在
modules:done钩子中注入 plugin.ts 与 payload-plugin.ts 两个运行时插件(且保证在路由插件之前注册)。
配置完成后,正常使用 store 即可:
// stores/user.ts
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', () => {
const name = ref('')
async function fetchUser() {
// ...
}
return { name, fetchUser }
})
<!-- pages/index.vue -->
<script setup>
const store = useUserStore()
</script>
在页面中等待 actions 完成
与 onServerPrefetch() 类似,你可以在 callOnce() 组合式函数中调用 store action。这样 Nuxt 只会执行该 action 一次,避免重复请求已经存在的数据:
<script setup>
const store = useUserStore()
// 也可以把 data 提取出来,但它已经在 store 中了
await callOnce('user', () => store.fetchUser())
</script>
根据需求,你可以选择只在客户端执行一次,或者在每次导航时都执行(后者更接近 useFetch() / useAsyncData() 的数据获取行为):
<script setup>
const store = useUserStore()
await callOnce('user', () => store.fetchUser(), { mode: 'navigation' })
</script>
在 asyncData() 中调用 store
如果想在 setup() 之外使用 store(例如 asyncData() 或 fetch()),需要把 pinia 实例传给 useStore()。@pinia/nuxt 已把 pinia 注入到 Nuxt 上下文中,可以直接通过 $pinia 访问:
import { useStore } from '~/stores/myStore'
export default {
asyncData({ $pinia }) {
const store = useStore($pinia)
// ...
},
}
与 onServerPrefetch() 一样,在 asyncData() 中调用 store action 不需要任何额外处理:
<script setup>
const store = useStore()
const { data } = await useAsyncData('user', () => store.fetchUser())
</script>
在非注入感知的上下文中使用 store
在 Navigation guards、其他 store、Nuxt Middleware 等非 setup() 或注入感知上下文中,请务必把 pinia 实例显式传给 useStore():
import { useStore } from '~/stores/myStore'
// 这行通常位于一个能够获取 pinia 实例的函数内部
const store = useStore(pinia)
幸运的是,在绝大多数场景下你都不需要经历这些繁琐步骤。其背后的原理是:usePinia() 封装了 useNuxtApp().$pinia(见 packages/nuxt/src/runtime/composables.ts),而该 $pinia 正是 plugin.ts 中通过 provide 注入的实例。Pinia 官方在 核心概念·组件外使用 中对此有更完整的论述。
自动引入(Auto imports)
模块默认暴露的自动引入
默认情况下,@pinia/nuxt 暴露若干自动引入,你无需手动 import:
| 名称 | 说明 |
|---|---|
usePinia() |
类似 getActivePinia(),但在 Nuxt 中效果更好(直接读取 useNuxtApp().$pinia) |
defineStore() |
定义 store |
storeToRefs() |
从 store 中解构出单个 ref |
acceptHMRUpdate() |
用于热更新(HMR) |
这些自动引入由 module.ts 中的 addImports 显式注册,其来源均为 runtime 下的 composables.ts(该文件通过 export * from 'pinia' 透传了 pinia 的全部导出)。
自动引入 store 目录(storesDirs)
模块还会自动引入 stores 目录下定义的所有 store(在 Nuxt 4 的新目录结构中为 app/stores)。不过它不会递归查找嵌套 store。可以通过 pinia.storesDirs 配置项自定义:
// nuxt.config.ts
export default defineNuxtConfig({
// ... 其他配置
modules: ['@pinia/nuxt'],
pinia: {
storesDirs: ['./stores/**', './custom-folder/stores/**'],
},
})
几点重要说明:
- 目录路径相对于项目根目录;如果你修改了
srcDir选项,需要相应调整路径。 - 若想引入嵌套 store,使用 glob 模式
./stores/**(Nuxt 3)或app/stores/**(Nuxt 4+)。 - 在模块源码中,默认值即
<a href="https://link.gitcode.com/i/03276e6e003140b84e21813f24354a80" target="_blank">resolve(nuxt.options.srcDir, 'stores')](见 [module.ts),并通过getLayerDirectories(nuxt)对每个 Nuxt layer 的app目录执行addImportsDir(见 module.ts),因此也天然支持 Nuxt layers 中位于layers/*/stores的 store。
仓库中的 playground 就是一个实际例子(packages/nuxt/playground/nuxt.config.ts):
pinia: {
storesDirs: ['./stores/**', './domain/*/stores'],
}
它同时引入了顶层 stores/(含 counter.ts、with-skip-hydrate.ts、nested/some-store.ts 等)与 domain/*/stores(如 packages/nuxt/playground/domain/one/stores/testStore.ts)目录中的 store。
自定义自动引入
@pinia/nuxt 也支持通过模块数组形式配置 autoImports 选项来定制自动引入,例如自动引入 defineStore() 并可选地重命名:
// nuxt.config.js
export default defineNuxtConfig({
// ... 其他配置
modules: [
// ...
[
'@pinia/nuxt',
{
autoImports: [
// 自动引入 `defineStore()`
'defineStore',
// 自动引入 `defineStore()` 并重命名为 `definePiniaStore()`
['defineStore', 'definePiniaStore'],
],
},
],
],
})
SSR 状态下探:payload 序列化与 skipHydrate
很多读者会好奇“Nuxt 帮我们处理了序列化”具体是怎么实现的。答案就在模块注入的第二个运行时插件 payload-plugin.ts 中:
import { shouldHydrate } from 'pinia'
const payloadPlugin = definePayloadPlugin(() => {
definePayloadReducer(
'skipHydrate',
(data: unknown) => !shouldHydrate(data) && 1
)
definePayloadReviver('skipHydrate', (_data: 1) => undefined)
})
它利用 Nuxt 的 payload reducer/reviver 机制,把被 skipHydrate() 标记的状态在服务端 → 客户端的 payload 中剔除,避免把不需要的数据(例如仅服务端使用的敏感字段或大对象)发送给客户端。
同时,主插件 plugin.ts 在两个环节完成状态迁移:
- 客户端激活时:若
nuxtApp.payload.pinia存在,则执行pinia.state.value = nuxtApp.payload.pinia恢复服务端状态; - 服务端渲染完成时:通过
app:rendered钩子把toRaw(nuxtApp.$pinia).state.value写入nuxtApp.payload.pinia,随后setActivePinia(undefined)清理服务端引用,避免内存占用。
在 store 中使用 skipHydrate() 的示例(见 packages/nuxt/playground/stores/with-skip-hydrate.ts):
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 }
})
开发体验:自动 HMR 注册
在开发模式下,模块还会注册一个 Vite 插件 pinia:auto-hmr-registration(见 packages/nuxt/src/auto-hmr-plugin.ts)。它通过 AST 解析源码,为顶层使用 defineStore 声明的 store 自动追加:
if (import.meta.hot) {
import.meta.hot.accept(acceptHMRUpdate(StoreName, import.meta.hot))
}
这样在修改 store 文件时,无需手写 acceptHMRUpdate 也能获得正确的热更新体验(保存状态而不重置)。模块源码中该插件仅在 nuxt.options.dev 时注册(module.ts)。如果你想在非 Nuxt 环境下手动处理 HMR,可参考热模块替换实战。
纯 Nuxt 2(不使用 Bridge)
适用前提:
@pinia/nuxt版本低于 0.2.1 时支持纯 Nuxt 2;@pinia/nuxt0.3.0 之后的版本面向 Nuxt 3/4,Nuxt 2 用户请固定使用旧版本。
安装时需要同时安装 @nuxtjs/composition-api:
yarn add pinia @pinia/nuxt@0.2.1 @nuxtjs/composition-api
# 使用 npm
npm install pinia @pinia/nuxt@0.2.1 @nuxtjs/composition-api
在 nuxt.config.js 的 buildModules 中注册(注意与 Nuxt 3/4 的 modules 区别):
// nuxt.config.js
export default {
// ... 其他配置
buildModules: [
// 仅支持 Nuxt 2:
'@nuxtjs/composition-api/module',
'@pinia/nuxt',
],
}
Nuxt 2 + TypeScript
如果你在 Nuxt 2(@pinia/nuxt < 0.3.0)下使用 TypeScript 且项目中有 jsconfig.json,需要为 context.pinia 引入类型:
{
"types": [
// ...
"@pinia/nuxt"
]
}
这样也能同时获得自动补全支持。
Pinia 与 Vuex 同时使用
官方建议避免同时使用 Pinia 和 Vuex,但如果你确实需要共存(例如渐进式迁移期间),需要告诉 Pinia 不要禁用 Vuex——把 disableVuex 设为 false:
// nuxt.config.js
export default {
buildModules: [
'@nuxtjs/composition-api/module',
['@pinia/nuxt', { disableVuex: false }],
],
// ... 其他配置
}
该选项仅存在于兼容 Nuxt 2 的旧版 @pinia/nuxt(v0.2.x)中;新版模块源码的 ModuleOptions(见 packages/nuxt/src/module.ts)仅包含 storesDirs 一个配置项。
常见问题与最佳实践小结
- 安装报 ERESOLVE:在
package.json增加"overrides": { "vue": "latest" }。 - 忘记装
@vue/devtools-api:pinia v4 起必须显式安装(手动安装请带上它)。 - 嵌套 store 无法自动引入:
storesDirs默认不递归,请显式使用./stores/**glob。 - 在路由守卫/Middleware 中拿不到 pinia:显式把
pinia实例传给useStore(pinia)。 - 服务端特有的数据不应下发客户端:用
skipHydrate()标记,配合shouldHydrate()判断。 - 版本选择:Nuxt 3.15+/4/5 使用当前
@pinia/nuxt;纯 Nuxt 2 固定使用@pinia/nuxt@0.2.1+@nuxtjs/composition-api,并注意disableVuex仅在旧版可用。
更多延伸阅读:SSR 应用整体指南见 SSR 索引,Nuxt 相关细节可对照英文原版 ssr/nuxt;状态在 setup() 外使用的完整说明见 组件外使用 store。