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,每个域内部再细分。
// 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),
};
}
// 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。
// 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 };
});
组合模式的关键注意事项:
- 避免循环依赖:Store A 依赖 Store B,Store B 又依赖 Store A,这会导致初始化时的无限递归。如果发现循环依赖,说明职责划分有问题,需要提取共享逻辑到第三个 Store。
- 延迟初始化:在 Setup Store 中调用
useXxxStore()是安全的,Pinia 会确保被依赖的 Store 在使用时已初始化。但在 Store 的顶层(模块加载时)不要直接调用——应在 setup 函数内部调用。 - 依赖最小化:一个 Store 依赖的 Store 数量最好不超过 2-3 个。如果依赖链太长,说明 Store 耦合度过高。
状态持久化方案:localStorage / IndexedDB / 服务端同步
状态持久化的需求场景:刷新页面后保持登录态、离线场景缓存数据、跨 Tab 同步状态。不同场景需要不同的持久化策略。
登录态持久化——安全敏感数据用 sessionStorage 或 HttpOnly Cookie,不要放 localStorage:
// 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:
// 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 间的状态同步:
// 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。
// 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 日志:
// 开发环境下的 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,需要手动实现:
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,避免对数组每个元素做深度响应式转换:
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 依赖了整个大数组但只用了其中几个字段,考虑先把需要的字段提取出来:
// 不理想:依赖整个 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 模型天然鼓励按功能域拆分,状态归属更清晰。
迁移策略建议分步进行:
- 新功能直接用 Pinia,不碰 Vuex
- 用
pinia-composition桥接层让 Pinia Store 读取 Vuex 状态 - 按功能域逐步迁移,每次迁移一个域并删除对应 Vuex module
- 最后移除 Vuex 依赖
不要做"大爆炸"式迁移——一次性替换所有 Store 的风险太高,且无法逐步验证。
最佳实践与常见陷阱
陷阱 1:Store 里放太多 UI 状态。 弹窗开关、表单临时状态不应该放 Store——它们的生命周期和组件一致,放 Store 只会增加复杂度而没有复用价值。判断标准:如果这个状态只有一个组件用,不要放 Store。
陷阱 2:在 Store 中直接做 API 请求而不处理竞态。 快速切换页面时,旧请求可能在新请求之后返回,导致数据覆盖。用 AbortController 或请求 ID 做竞态控制:
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 迁移时分步进行,新功能先行,老功能按域逐步切换,降低风险的同时让团队逐步适应新的架构模式。
