在 Nuxt 中集成 Pinia:SSR 友好的状态管理完整指南

原创2026-09-21 14:21:111,875 阅读
文章标签:前端状态管理

在 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。模块初始化时还会做两件关键事情:

  1. 把 runtime 目录加入 build.transpile,并让 Vite 的 optimizeDeps.exclude 排除 pinia,避免项目中出现多份 Pinia 副本;
  2. 在 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/nuxt 0.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 一个配置项。


常见问题与最佳实践小结

  1. 安装报 ERESOLVE:在 package.json 增加 "overrides": { "vue": "latest" }。
  2. 忘记装 @vue/devtools-api:pinia v4 起必须显式安装(手动安装请带上它)。
  3. 嵌套 store 无法自动引入:storesDirs 默认不递归,请显式使用 ./stores/** glob。
  4. 在路由守卫/Middleware 中拿不到 pinia:显式把 pinia 实例传给 useStore(pinia)。
  5. 服务端特有的数据不应下发客户端:用 skipHydrate() 标记,配合 shouldHydrate() 判断。
  6. 版本选择: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。

登录后查看全文
pinia