Skip to content

Pinia 大型项目状态管理:模块化设计与持久化策略

Pinia 作为 Vue 官方推荐的状态管理库,API 简洁、TypeScript 友好、Devtools 集成完善。在中小型项目中,几乎不需要太多架构思考就能用好。但当项目规模增长到几十个页面、上百个 API 接口、多个业务团队并行开发时,Pinia 的使用方式需要从"写 Store"升级到"设计 Store 架构"。

大型项目中的 Store 架构设计 ​

大型项目的状态管理问题,本质上不是 Pinia 的 API 问题,而是状态归属问题——哪些状态该放 Store、哪些该放组件本地、哪些该放服务端缓存。一个常见的错误是把所有状态都塞进 Store,导致 Store 膨胀、组件失去自主性、不必要的全局响应式开销。

状态归属的判断原则:

  • 服务端数据的缓存:多个组件共享的列表/详情数据放 Store,配合请求去重
  • 跨页面共享的用户态:登录信息、权限、偏好设置放 Store
  • 页面级 UI 状态:当前打开的 Tab、表单草稿放 Store(支持页面切换恢复)
  • 组件内部状态:弹窗开关、输入框聚焦等放组件本地 ref/reactive
  • 派生数据:用 computed 或 getters,不要存储可计算的数据

Store 的模块化拆分:按功能域 vs 按页面 ​

拆分 Store 有两种常见策略:按功能域(domain)或按页面(page)。

按页面拆分的问题在于页面边界不稳定——产品迭代会合并、拆分页面,而且跨页面的共享状态(如用户信息)没有自然归属。

按功能域拆分更合理。功能域是业务概念的边界,比页面稳定。例如一个电商平台可以按"用户域"、"商品域"、"订单域"、"支付域"拆分 Store,每个域内部再细分。

typescript
// stores/domain/user/index.ts
import { defineStore } from 'pinia';
import { useAuthStore } from './auth';
import { useProfileStore } from './profile';
import { usePermissionStore } from './permission';

// 域级聚合 Store:对外暴露统一入口
export function useUserDomain() {
  const auth = useAuthStore();
  const profile = useProfileStore();
  const permission = usePermissionStore();

  return {
    auth,
    profile,
    permission,
    // 域级派生状态
    isLoggedIn: () => auth.token !== null,
    canAccess: (resource: string) => permission.check(resource),
  };
}
typescript
// stores/domain/user/auth.ts - 认证 Store
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { authApi } from '@/api/auth';

export const useAuthStore = defineStore('auth', () => {
  const token = ref<string | null>(null);
  const refreshToken = ref<string | null>(null);
  const expiresAt = ref<number>(0);

  const isAuthenticated = computed(() => {
    return token.value !== null && Date.now() < expiresAt.value;
  });

  async function login(credentials: LoginCredentials) {
    const result = await authApi.login(credentials);
    token.value = result.accessToken;
    refreshToken.value = result.refreshToken;
    expiresAt.value = Date.now() + result.expiresIn * 1000;
  }

  async function refresh() {
    if (!refreshToken.value) throw new Error('No refresh token');
    const result = await authApi.refresh(refreshToken.value);
    token.value = result.accessToken;
    expiresAt.value = Date.now() + result.expiresIn * 1000;
  }

  function logout() {
    token.value = null;
    refreshToken.value = null;
    expiresAt.value = 0;
  }

  return { token, isAuthenticated, login, refresh, logout };
});

每个功能域内部,Store 保持在 100-200 行以内。如果一个 Store 超过这个规模,说明需要进一步拆分——通常可以按读操作和写操作分离,或者按实体类型拆分。

跨 Store 依赖管理:组合 vs 继承 ​

大型项目中 Store 之间必然存在依赖关系。用户订单 Store 需要读取用户信息 Store,权限 Store 依赖认证 Store 的 token。Pinia 处理跨 Store 依赖的方式是组合——在一个 Store 内部调用另一个 Store。

typescript
// stores/domain/order/list.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { useAuthStore } from '../user/auth';
import { usePermissionStore } from '../user/permission';
import { orderApi } from '@/api/order';

export const useOrderListStore = defineStore('order-list', () => {
  // 组合其他 Store
  const auth = useAuthStore();
  const permission = usePermissionStore();

  const orders = ref<Order[]>([]);
  const loading = ref(false);
  const filter = ref<OrderFilter>({ status: 'all' });

  const visibleOrders = computed(() => {
    if (permission.canViewAllOrders()) {
      return orders.value;
    }
    // 普通用户只能看到自己的订单
    return orders.value.filter((o) => o.userId === auth.userId);
  });

  async function fetchOrders() {
    if (!auth.isAuthenticated) return;

    loading.value = true;
    try {
      orders.value = await orderApi.list({
        filter: filter.value,
        token: auth.token!,
      });
    } finally {
      loading.value = false;
    }
  }

  return { orders, visibleOrders, loading, filter, fetchOrders };
});

组合模式的关键注意事项:

  1. 避免循环依赖:Store A 依赖 Store B,Store B 又依赖 Store A,这会导致初始化时的无限递归。如果发现循环依赖,说明职责划分有问题,需要提取共享逻辑到第三个 Store。
  2. 延迟初始化:在 Setup Store 中调用 useXxxStore() 是安全的,Pinia 会确保被依赖的 Store 在使用时已初始化。但在 Store 的顶层(模块加载时)不要直接调用——应在 setup 函数内部调用。
  3. 依赖最小化:一个 Store 依赖的 Store 数量最好不超过 2-3 个。如果依赖链太长,说明 Store 耦合度过高。

状态持久化方案:localStorage / IndexedDB / 服务端同步 ​

状态持久化的需求场景:刷新页面后保持登录态、离线场景缓存数据、跨 Tab 同步状态。不同场景需要不同的持久化策略。

登录态持久化——安全敏感数据用 sessionStorage 或 HttpOnly Cookie,不要放 localStorage:

typescript
// plugins/persist-auth.ts
import type { PiniaPluginContext } from 'pinia';

const PERSIST_KEYS: Record<string, string[]> = {
  auth: ['token', 'refreshToken', 'expiresAt'],
  preference: ['theme', 'language', 'sidebarCollapsed'],
};

export function persistPlugin({ store }: PiniaPluginContext) {
  const keys = PERSIST_KEYS[store.$id];
  if (!keys) return;

  // 恢复持久化数据
  const stored = localStorage.getItem(`pinia:${store.$id}`);
  if (stored) {
    const parsed = JSON.parse(stored);
    keys.forEach((key) => {
      if (key in parsed) store[key] = parsed[key];
    });
  }

  // 监听变化并持久化
  store.$subscribe((mutation, state) => {
    const toPersist: Record<string, unknown> = {};
    keys.forEach((key) => {
      toPersist[key] = state[key];
    });
    localStorage.setItem(`pinia:${store.$id}`, JSON.stringify(toPersist));
  });
}

大量数据缓存——如商品列表、聊天记录,localStorage 的 5MB 限制不够用,需要 IndexedDB:

typescript
// utils/idb-persist.ts
import { openDB, type IDBPDatabase } from 'idb';

let dbPromise: Promise<IDBPDatabase> | null = null;

function getDB() {
  if (!dbPromise) {
    dbPromise = openDB('app-cache', 1, {
      upgrade(db) {
        db.createObjectStore('stores', { keyPath: 'id' });
      },
    });
  }
  return dbPromise;
}

export async function persistToIDB(key: string, data: unknown) {
  const db = await getDB();
  await db.put('stores', { id: key, data, timestamp: Date.now() });
}

export async function loadFromIDB(key: string, maxAge = 5 * 60 * 1000) {
  const db = await getDB();
  const record = await db.get('stores', key);
  if (!record) return null;
  if (Date.now() - record.timestamp > maxAge) {
    await db.delete('stores', key);
    return null;
  }
  return record.data;
}

跨 Tab 同步——用 BroadcastChannel 实现多 Tab 间的状态同步:

typescript
// plugins/cross-tab-sync.ts
export function crossTabSyncPlugin({ store }: PiniaPluginContext) {
  if (typeof window === 'undefined') return;
  if (!('BroadcastChannel' in window)) return;

  const channel = new BroadcastChannel(`pinia:${store.$id}`);

  // 接收其他 Tab 的状态更新
  channel.onmessage = (event) => {
    const { type, payload } = event.data;
    if (type === 'sync') {
      store.$patch(payload);
    }
  };

  // 广播状态变化
  store.$subscribe((mutation, state) => {
    channel.postMessage({ type: 'sync', payload: state });
  });
}

SSR 友好的状态管理:Hydration 与状态序列化 ​

Nuxt 3 / SSR 场景下,Pinia 需要处理服务端预取数据 → 序列化到 HTML → 客户端 hydration 的完整链路。核心是确保客户端的初始状态与服务端一致,避免 hydration mismatch。

typescript
// Nuxt 3 中的 SSR 状态处理
// server/plugins/pinia-ssr.ts
import { defineNuxtPlugin } from '#app';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('app:created', async () => {
    const pinia = nuxtApp.$pinia;

    // 在服务端预取关键数据
    const authStore = useAuthStore(pinia);
    if (nuxtApp.ssrContext?.event.req.headers.cookie) {
      await authStore.initFromCookie(nuxtApp.ssrContext.event.req.headers.cookie);
    }

    const preferenceStore = usePreferenceStore(pinia);
    await preferenceStore.fetchPreferences();
  });
});

// 客户端 hydration
// Nuxt 自动处理 state 序列化,但需要确保 Store 是 SSR 友好的
export const useAuthStore = defineStore('auth', () => {
  const token = ref<string | null>(null);

  // 避免在 Store 顶层访问 window/document
  // 这些 API 只在客户端可用
  function initFromCookie(cookie: string) {
    const match = cookie.match(/auth_token=([^;]+)/);
    token.value = match ? match[1] : null;
  }

  return { token, initFromCookie };
});

SSR 中最常见的坑是 Store 中直接调用了浏览器 API(如 window.localStorage)。解决方式是用 import.meta.server / import.meta.client 做环境判断,或者把浏览器 API 访问延迟到 onMounted 中。

Devtools 集成与调试技巧 ​

Pinia Devtools 提供了时间旅行调试、状态快照、action 追踪等能力。在大型项目中,几个实用的调试技巧:

$onAction 订阅——在不修改 Store 代码的情况下添加 action 日志:

typescript
// 开发环境下的 action 追踪
if (import.meta.env.DEV) {
  const pinia = getActivePinia()!;
  pinia.use(({ store }) => {
    store.$onAction(({ name, args, after, onError }) => {
      const startTime = Date.now();
      console.log(`[${store.$id}] ${name}() called`, args);

      after((result) => {
        console.log(`[${store.$id}] ${name}() done in ${Date.now() - startTime}ms`);
      });

      onError((error) => {
        console.error(`[${store.$id}] ${name}() failed`, error);
      });
    });
  });
}

$reset 状态重置——测试和路由切换时恢复 Store 到初始状态。Setup Store 默认不支持 $reset,需要手动实现:

typescript
export const useOrderListStore = defineStore('order-list', () => {
  const orders = ref<Order[]>([]);
  const filter = ref<OrderFilter>({ status: 'all' });

  function $reset() {
    orders.value = [];
    filter.value = { status: 'all' };
  }

  return { orders, filter, $reset };
});

性能优化:避免不必要的响应式追踪 ​

大型项目中 Store 的性能问题通常不是来自 Pinia 本身,而是来自不合理的响应式使用。

大数组只读场景:如果一个数组数据只用于渲染、不需要响应式追踪内部属性变化,用 shallowRef 替代 ref,避免对数组每个元素做深度响应式转换:

typescript
export const useProductListStore = defineStore('product-list', () => {
  // shallowRef:只追踪 .value 的替换,不追踪内部属性变化
  const products = shallowRef<Product[]>([]);
  const loading = ref(false);

  async function fetchProducts() {
    loading.value = true;
    try {
      products.value = await productApi.list();
    } finally {
      loading.value = false;
    }
  }

  return { products, loading, fetchProducts };
});

computed 缓存策略:对于计算成本高的派生数据,确保 computed 的依赖最小化。如果一个 computed 依赖了整个大数组但只用了其中几个字段,考虑先把需要的字段提取出来:

typescript
// 不理想:依赖整个 orders 数组
const totalAmount = computed(() =>
  orders.value.reduce((sum, o) => sum + o.amount, 0),
);

// 更好:依赖提取出的金额数组,数组替换时才重算
const orderAmounts = computed(() => orders.value.map((o) => o.amount));
const totalAmount = computed(() =>
  orderAmounts.value.reduce((sum, a) => sum + a, 0),
);

实际上,第二种写法在 orders 数组元素属性变化时不会触发重算(因为 map 产生新数组),这在某些场景下是优势。但如果 orders 内部频繁变化,第一种写法更安全。需要根据实际场景权衡。

与 Vuex 的迁移经验 ​

从 Vuex 迁移到 Pinia 的项目,最大的收益不是 API 更简洁,而是架构约束的变化。Vuex 的单一 Store 树容易导致"全局状态垃圾桶"——所有模块都往一个 Store 里塞数据。Pinia 的多 Store 模型天然鼓励按功能域拆分,状态归属更清晰。

迁移策略建议分步进行:

  1. 新功能直接用 Pinia,不碰 Vuex
  2. 用 pinia-composition 桥接层让 Pinia Store 读取 Vuex 状态
  3. 按功能域逐步迁移,每次迁移一个域并删除对应 Vuex module
  4. 最后移除 Vuex 依赖

不要做"大爆炸"式迁移——一次性替换所有 Store 的风险太高,且无法逐步验证。

最佳实践与常见陷阱 ​

陷阱 1:Store 里放太多 UI 状态。 弹窗开关、表单临时状态不应该放 Store——它们的生命周期和组件一致,放 Store 只会增加复杂度而没有复用价值。判断标准:如果这个状态只有一个组件用,不要放 Store。

陷阱 2:在 Store 中直接做 API 请求而不处理竞态。 快速切换页面时,旧请求可能在新请求之后返回,导致数据覆盖。用 AbortController 或请求 ID 做竞态控制:

typescript
let fetchController: AbortController | null = null;

async function fetchOrders() {
  fetchController?.abort();
  fetchController = new AbortController();

  try {
    orders.value = await orderApi.list({
      signal: fetchController.signal,
    });
  } catch (e) {
    if (!(e instanceof DOMException && e.name === 'AbortError')) {
      throw e;
    }
  }
}

陷阱 3:过度使用 $patch 批量更新。 $patch 适合批量更新多个不相关字段,但如果更新逻辑有依赖关系(如先设置 A 再根据 A 计算 B),应该用 action 函数保证逻辑清晰。

小结 ​

Pinia 在大型项目中的架构设计核心是:按功能域拆分 Store、用组合模式管理跨 Store 依赖、根据数据特性选择持久化方案(小数据用 localStorage、大数据用 IndexedDB、跨 Tab 用 BroadcastChannel)、SSR 场景注意 hydration 一致性、用 shallowRef 和合理 computed 优化性能。状态管理没有银弹——关键是理解每个状态的生命周期和访问模式,让架构服务于业务而非反之。从 Vuex 迁移时分步进行,新功能先行,老功能按域逐步切换,降低风险的同时让团队逐步适应新的架构模式。

MIT Licensed