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 for 小數據、IndexedDB for 大數據、BroadcastChannel for 跨 Tab)、SSR 場景注意 hydration 一致性、用 shallowRef 和合理 computed 優化性能。狀態管理沒有銀彈——關鍵是理解每個狀態的生命周期和訪問模式,讓架構服務於業務而非反之。從 Vuex 遷移時分步進行,新功能先行,老功能按域逐步切換,降低風險的同時讓團隊逐步適應新的架構模式。
