管理全解析：核心原理、模塊拆分與高頻踩坑)
Vuex 這玩意兒現(xiàn)在提起來有點微妙。新項目里 Pinia 基本是默認選項很多人一上手 Vue 3 就沒碰過 Vuex。但你去翻一翻手上維護的那些跑了三四年的中后臺系統(tǒng)十有八九還在store/index.js里躺著幾十個 mutation改一個字段要先找 action、再找 mutation、最后才敢動 state。這時候你要是連 Vuex 的執(zhí)行鏈路都說不清楚排查問題基本靠猜。這篇就把 Vuex 的知識點掰開揉碎講透從“到底什么時候該用它”到“store 怎么拆模塊”再到“為什么我的 commit 沒生效”這類真實踩坑全部過一遍。適合兩類人看一類是剛接手老項目、被mapState和各種root: true繞暈的新手另一類是想把狀態(tài)管理這塊徹底搞清楚、以后不管換 Pinia 還是別的庫都能快速上手的同學。代碼以 Vuex 4 Vue 3 為主線涉及 Vue 2 的差異我會單獨標出來。1. 先搞清楚什么時候真的需要 Vuex1.1 狀態(tài)管理的邊界到底在哪我在帶人的時候發(fā)現(xiàn)一個特別普遍的問題很多人學完 Vuex 的第一反應是“好東西全塞進去”。結果一個只有三個頁面的小工具store 里堆了二十多個字段其中一半是某個組件內部的彈窗開關。這就屬于把狀態(tài)管理當成了全局變量倉庫最后維護成本比不用還高。判斷一個狀態(tài)該不該進 store我一般看三條第一這份數據是不是被兩個以上互不相鄰的組件同時使用。父子組件之間傳值props加emit就夠了爺孫層級深一點provide/inject也能解決。只有當兄弟組件、或者跨了好幾層的遠房親戚都要讀寫同一份數據時才輪到 Vuex 出場。第二這份數據是不是跨越了路由。比如登錄態(tài)、用戶信息、權限菜單從 A 頁面跳到 B 頁面還得用這種放在組件里必然會隨著組件銷毀而丟失必須提上去。第三這份數據變更后是不是需要留下可追溯的痕跡。Vuex 配 devtools 能記錄每一次 mutation 的時間旅行對于復雜的表單聯(lián)動、購物車增刪改這個調試能力值不少時間。反過來說哪些不該進 store組件的 loading 狀態(tài)、某個列表的滾動位置、彈窗的顯隱開關這些都屬于“局部狀態(tài)”跟著組件生命周期走才是最干凈的。我見過有人把dialogVisible放進 store結果兩個頁面復用同一個彈窗組件時互相干擾排查了半天才發(fā)現(xiàn)是狀態(tài)被共享了。記住一句話狀態(tài)放得越高耦合就越重能不升就不升。還有一種常見誤區(qū)是把接口返回的原始數據全量塞進 store然后組件里再filter一遍。這樣做的問題在于 store 變成了緩存層但你又沒做失效策略最后數據新舊不一致的 bug 特別難查。我的習慣是 store 只存“經過業(yè)務加工、有明確語義”的狀態(tài)原始響應體在 action 里處理完就丟掉。1.2 Vuex 和 Pinia 到底怎么選這個話題繞不開。Pinia 確實是官方現(xiàn)在主推的方案API 更簡潔、TypeScript 支持更好、沒有 mutation 這一層。但“新項目用 Pinia”不等于“Vuex 就沒用了”。我整理了一張對照表你對著自己項目的情況看就行。對比維度Vuex 4Pinia變更入口mutation 提交action 觸發(fā)直接改 stateaction 里也能改模塊機制modules namespaced 嵌套每個 store 天然獨立TypeScript 支持需要額外類型聲明較繁瑣原生推導幾乎零配置devtools 時間旅行支持粒度到 mutation支持粒度到 action代碼量一個功能要寫 state/getter/mutation/action 四份基本一份 setup 或 option 就夠學習曲線概念多鏈路長概念少接近組合式函數存量項目兼容原生可與 Vuex 共存逐模塊遷移適合場景老項目維護、團隊已有約定新項目、TS 重度使用我的實際經驗是已經在跑的 Vuex 項目別為了追新去動它。遷移本身不難難的是遷移期間兩套狀態(tài)管理并存帶來的心智負擔以及測試覆蓋不足時的回歸風險。真要遷也是按模塊一個個搬先把用戶模塊搬過去跑一周沒問題再搬下一個。反倒是新起的項目沒有歷史包袱直接上 Pinia 更省事。不過有一點要說清楚Vuex 那套“mutation 必須同步、action 處理異步”的約束雖然寫起來啰嗦但它強迫你把“改數據”和“做業(yè)務”分開這個思維在團隊協(xié)作里是有價值的。很多 Pinia 新手直接在 action 里一頓this.xxx yyy出了問題連是哪一步改的都定位不到。所以就算你用的是 Pinia也建議保留“純函數式改狀態(tài)”的習慣。1.3 一張判斷清單幫你決定要不要引入我給自己團隊寫過一個很土但很好用的清單五個問題中三個以上才考慮上 Vuex有沒有一份數據被三個以上的組件讀取且這些組件不在同一條父子鏈上這份數據會不會因為路由切換而需要保留這份數據的修改是否需要多人協(xié)作、且改動點分散在多個文件出問題時是否需要回放“誰在什么時候改了什么”項目規(guī)模是不是已經超過二十個頁面或者五個以上的業(yè)務模塊如果只中一兩條老老實實用props加組合式函數封裝別給自己找事。狀態(tài)管理的本質是降低溝通成本不是炫技。2. Vuex 的五個核心概念一次捋直2.1 state單一狀態(tài)樹和它的設計原則Vuex 把所有狀態(tài)收攏到一棵樹里官方叫單一狀態(tài)樹Single Source of Truth。好處是任何一個時刻你都能通過store.state拿到應用完整的數據快照調試的時候特別直觀。壞處是這棵樹如果沒人管長到幾百個字段之后新人進來根本看不懂哪個字段屬于哪個業(yè)務。我的做法是按業(yè)務域切分而不是按數據類型切分。什么叫按數據類型切就是state.list、state.detail、state.loading這么平鋪看著整齊實際上一旦業(yè)務變多就全亂。按業(yè)務域切就是user、order、permission各占一塊每個模塊自洽。具體到寫法Vuex 4 里定義模塊的 state 一定要用函數返回對象// store/modules/user.js const state () ({ profile: null, token: , roles: [], permissionLoaded: false })為什么必須是函數因為模塊在注冊時會被合并進根 state如果直接寫對象字面量多個組件實例或者熱更新場景下會共享同一份引用出現(xiàn)“A 頁面改了 B 頁面也變了”的靈異事件。這個坑我在服務端渲染的項目里踩過一次排查了整整一個下午。另外 state 里的字段命名要帶語義。data、info、list這種詞盡量別用orderList、userProfile、pendingTaskCount一眼就知道是什么。字段一多命名就是最好的文檔。2.2 getters派生狀態(tài)和它的緩存機制getters 可以理解為 store 里的 computed。它的返回值會基于依賴做緩存依賴不變就不重新計算。這個特性用好了能省不少性能用不好反而會成為 bug 來源。const getters { isLogin: state Boolean(state.token), displayName: state state.profile?.nickname || state.profile?.username || 未登錄, // 依賴其他 getter第二個參數是當前模塊的 getters welcomeText: (state, getters) ${getters.displayName}歡迎回來, // 依賴根 state第四個參數是 rootState hasPermission: (state, getters, rootState) code { return state.roles.includes(code) || rootState.user.roles.includes(code) } }這里有個關鍵點getter 返回函數時緩存就失效了。上面hasPermission返回的是一個函數每次調用都會重新執(zhí)行因為 Vue 沒法追蹤函數內部用到的參數。這種寫法適合做權限判斷這類需要傳參的場景但別在模板里高頻調用它尤其是列表渲染里v-for每一項都調一次性能會明顯下降。真要這么用先在 computed 里把結果算好。還有一個容易翻車的地方getter 里返回新對象。比如// 不推薦每次都返回新數組緩存形同虛設 filteredList: state state.list.filter(item item.active)因為filter每次執(zhí)行都會產生新數組引用Vue 的依賴追蹤會認為結果變了導致依賴這個 getter 的組件反復更新。如果這個列表很大、更新又頻繁頁面會明顯卡頓。正確做法是把過濾邏輯放到組件 computed 里或者用shallowRef之類的思路做手動緩存。我在一個萬級數據的表格項目里就吃過這個虧后來把 getter 改成了只做簡單映射流暢度立刻回來了。2.3 mutations為什么它必須是同步的這是 Vuex 里被問得最多的問題?！拔揖驮?mutation 里發(fā)個請求怎么了”答案藏在 devtools 的工作原理里。devtools 記錄狀態(tài)變化的方式是每執(zhí)行一次 mutation就拍一張 state 的快照存進時間線。如果你在 mutation 里發(fā)異步請求那么“mutation 開始執(zhí)行”和“state 真正被改”之間存在時間差devtools 拍到的那張快照可能是請求還沒回來的中間態(tài)。等你點時間旅行回到某一步看到的狀態(tài)和實際不符調試就徹底失去了意義。所以 Vuex 強制 mutation 同步是為了保證每一幀快照都是確定性的。const mutations { SET_PROFILE(state, payload) { state.profile payload }, SET_TOKEN(state, token) { state.token token }, ADD_ROLE(state, role) { if (!state.roles.includes(role)) { state.roles.push(role) } }, RESET(state) { // 重置時不要直接替換整個 state 對象Vue 會丟失響應式追蹤 Object.assign(state, { profile: null, token: , roles: [], permissionLoaded: false }) } }mutation 的命名我統(tǒng)一用全大寫加下劃線這是社區(qū)慣例好處是在 devtools 列表里一眼就能和 action 區(qū)分開。action 用小駝峰比如fetchProfile。這套約定看起來是小事但團隊人多的時候能省掉很多溝通。還有一個細節(jié)mutation 里不要做副作用。什么叫副作用發(fā)請求、寫 localStorage、彈 toast這些都算。mutation 應該是一個純函數給它同樣的輸入state 就變成同樣的結果。這樣你寫單元測試的時候只需要斷言 state 變化不用 mock 一堆東西。2.4 actions異步編排和業(yè)務邏輯的落腳點action 是 Vuex 里唯一允許寫異步的地方它不直接改 state而是通過commit觸發(fā) mutation。這個設計看起來多繞了一層實際上把“業(yè)務流程”和“數據變更”解耦了。const actions { async fetchProfile({ commit, state, dispatch }, force false) { if (state.profile !force) { return state.profile } const res await api.getUserProfile() commit(SET_PROFILE, res.data) // 跨模塊調用要加 root: true await dispatch(permission/loadRoutes, res.data.roles, { root: true }) return res.data }, async login({ commit, dispatch }, { username, password }) { const { token } await api.login({ username, password }) commit(SET_TOKEN, token) await dispatch(fetchProfile, true) }, logout({ commit }) { commit(RESET) commit(permission/RESET, null, { root: true }) } }action 的返回值很重要。因為 action 內部是 Promise你可以在組件里await store.dispatch(login, form)拿到結果后再做跳轉或者提示。很多老代碼里 action 不 return組件只能靠 watch 某個 state 來判斷成功與否這種寫法非常脆弱。養(yǎng)成習慣action 有結果就 return 出去?？缒K dispatch 的{ root: true }是新手最容易漏的參數。不加這個參數Vuex 會只在當前模塊內查找 action找不到就靜默失敗或者報unknown action type。我第一次遇到的時候盯著代碼看了半小時最后發(fā)現(xiàn)就是少了個 root。2.5 modules 和 namespaced拆分與隔離項目一大單文件 store 必然爆炸。modules 就是用來拆的而namespaced: true決定了拆完之后彼此是否隔離。// store/index.js import { createStore } from vuex import user from ./modules/user import permission from ./modules/permission import cart from ./modules/cart export default createStore({ strict: import.meta.env.DEV, modules: { user: { namespaced: true, ...user }, permission: { namespaced: true, ...permission }, cart: { namespaced: true, ...cart } } })開不開命名空間我的答案是業(yè)務模塊一律開。不開的話所有模塊的 mutation 都注冊在全局兩個模塊都定義了SET_LOADING后注冊的會覆蓋前一個這種 bug 隱蔽性極強。開了之后方法名變成user/SET_LOADING雖然寫起來長一點但邊界清晰。全局的通用狀態(tài)比如 app 級別的主題、語言可以單開一個不開命名空間的 root 模塊但數量要克制。嵌套模塊的調用鏈路也要理清楚。假設有個setting模塊掛在user下面那么在setting的 action 里調用兄弟模塊路徑要寫成dispatch(cart/addItem, item, { root: true })。這個 root 參數指的是“從根開始找”不管你現(xiàn)在在哪一層。記不住的話就記一句只要跨出當前模塊就帶 root: true。3. 從零搭一個能落地的 Store 結構3.1 目錄設計和模塊拆分原則先看目錄這是我用了幾年、覺得最不容易亂的一種src/ ├── store/ │ ├── index.js // 入口注冊模塊和插件 │ ├── plugins/ │ │ └── persist.js // 持久化插件 │ ├── modules/ │ │ ├── user.js // 用戶信息、登錄態(tài) │ │ ├── permission.js // 路由權限、菜單 │ │ └── cart.js // 業(yè)務模塊示例 │ └── helpers.js // 通用工具比如生成 mutation types拆分粒度怎么定我的一般原則是一個模塊對應一個業(yè)務域而不是一個頁面。比如訂單列表和訂單詳情都屬于 order 模塊不要拆成兩個。反過來用戶和權限雖然是相關的但職責不同用戶管“我是誰”權限管“我能看什么”拆開更好維護。模塊內部的結構我習慣按state → getters → mutations → actions → 導出的順序寫和 Vuex 的執(zhí)行鏈路一致讀代碼的人從上往下看正好是數據流向。文件末尾統(tǒng)一導出export default { namespaced: true, state, getters, mutations, actions }有一點要注意如果模塊之間有數據依賴不要在模塊文件里直接import另一個模塊的 state那樣會造成循環(huán)依賴。正確方式是通過rootState讀取或者用dispatch讓對方的 action 來處理。3.2 完整實現(xiàn)一個購物車模塊光說概念沒意思直接上一個能跑的。假設我們要做一個購物車需求是加商品、改數量、刪除、算總價、選中狀態(tài)管理。// store/modules/cart.js const state () ({ items: [], // { id, name, price, count, checked } submitting: false }) const getters { totalCount: state state.items.reduce((sum, i) sum i.count, 0), checkedItems: state state.items.filter(i i.checked), totalPrice: (state, getters) { // 金額用分做單位避免浮點誤差最后再除以 100 const cents getters.checkedItems.reduce((sum, i) sum i.price * 100 * i.count, 0) return cents / 100 }, isAllChecked: state state.items.length 0 state.items.every(i i.checked) } const mutations { ADD_ITEM(state, product) { const exist state.items.find(i i.id product.id) if (exist) { exist.count 1 } else { state.items.push({ ...product, count: 1, checked: true }) } }, UPDATE_COUNT(state, { id, count }) { const item state.items.find(i i.id id) if (item) { item.count Math.max(1, Math.min(99, count)) } }, TOGGLE_CHECK(state, id) { const item state.items.find(i i.id id) if (item) item.checked !item.checked }, TOGGLE_ALL(state, checked) { state.items.forEach(i { i.checked checked }) }, REMOVE_ITEM(state, id) { state.items state.items.filter(i i.id ! id) }, SET_SUBMITTING(state, flag) { state.submitting flag }, CLEAR(state) { state.items [] } } const actions { async checkout({ commit, state, rootState }) { if (!state.items.length) return { ok: false, msg: 購物車是空的 } const payload state.items .filter(i i.checked) .map(i ({ productId: i.id, count: i.count })) commit(SET_SUBMITTING, true) try { const res await api.submitOrder({ items: payload, userId: rootState.user.profile?.id }) commit(REMOVE_ITEM_BATCH, res.data.removedIds) return { ok: true, orderId: res.data.orderId } } catch (e) { return { ok: false, msg: e.message } } finally { commit(SET_SUBMITTING, false) } } } export default { namespaced: true, state, getters, mutations, actions }這里有幾個我自己踩過坑之后固定下來的寫法。金額全部用“分”來算最后展示時再轉回元0.1 0.2那種經典浮點問題在電商場景真的會出事。數量做了Math.max(1, Math.min(99, count))的鉗制防止用戶在輸入框里手打負號或者超大批量。checkout的返回值統(tǒng)一成{ ok, msg }結構組件層不用 try-catch直接看ok就行。另外REMOVE_ITEM_BATCH我在 mutations 里沒寫實際項目中應該補上避免循環(huán)提交單條刪除。這類細節(jié)在真實業(yè)務里會因為批量操作導致幾十次 commitdevtools 面板直接被刷屏。3.3 組件里怎么調用四種方式對比Vuex 提供的調用方式有好幾種很多人只會mapState遇到方法就不知道咋辦了。列個表對照著記場景選項式寫法組合式寫法setup讀 statecomputed(() this.$store.state.user.profile)const profile computed(() store.state.user.profile)讀 getterthis.$store.getters[user/isLogin]computed(() store.getters[user/isLogin])觸發(fā) mutationthis.$store.commit(user/SET_TOKEN, t)store.commit(user/SET_TOKEN, t)觸發(fā) actionawait this.$store.dispatch(user/login, f)await store.dispatch(user/login, f)批量映射...mapState(user, [profile])storeToRefs(store.state.user)配合解構組合式 API 里推薦用useStore加storeToRefsimport { computed } from vue import { useStore } from vuex import { storeToRefs } from pinia // 注意Vuex 沒有官方 storeToRefs這里用 toRefs 替代 export default { setup() { const store useStore() // 直接解構會丟失響應式必須轉成 ref const { profile, token } toRefs(store.state.user) const isLogin computed(() store.getters[user/isLogin]) function handleAdd(product) { store.commit(cart/ADD_ITEM, product) } return { profile, token, isLogin, handleAdd } } }補充一句上面代碼里storeToRefs是 Pinia 的 APIVuex 項目要用 Vue 的toRefs配合store.state.模塊名。這個區(qū)別我見過不止一個人寫混。toRefs只能處理普通響應式對象store.state本身就是響應式的所以能用但store.getters不行因為 getters 是每次訪問時動態(tài)計算的得用computed包一層。選項式 API 里用輔助函數會簡潔很多import { mapState, mapGetters, mapActions } from vuex export default { computed: { ...mapState(cart, [items, submitting]), ...mapGetters(cart, [totalPrice, isAllChecked]), // 自己再算的派生值 isEmpty() { return this.items.length 0 } }, methods: { ...mapActions(cart, [checkout]), async onSubmit() { const res await this.checkout() if (res.ok) { // 跳轉邏輯 } } } }有個小坑要提醒mapState映射出來的名字如果和組件data里的字段重名Vue 會告警而且行為不確定。命名的時候盡量錯開或者在映射時用對象形式重命名...mapState(cart, { cartItems: items })。3.4 嚴格模式、持久化插件和 devtools 配置嚴格模式我強烈建議只在開發(fā)環(huán)境開const store createStore({ strict: import.meta.env.DEV, modules: { ... } })嚴格模式下任何不經過 mutation 的 state 修改都會拋錯[vuex] do not mutate vuex store state outside mutation handlers。這個檢查很耗性能因為它需要深度監(jiān)聽整棵 state 樹。生產環(huán)境開嚴格模式在大型應用里能明顯感覺到卡頓。用 Vite 的話import.meta.env.DEV就是現(xiàn)成的webpack 環(huán)境用process.env.NODE_ENV ! production。持久化這塊Vuex 本身不提供社區(qū)有插件但也都不太維護了我一般手寫一個三十行的插件// store/plugins/persist.js const KEY APP_STORE_V1 export default function createPersistPlugin(paths []) { return store { // 恢復 const raw localStorage.getItem(KEY) if (raw) { try { const saved JSON.parse(raw) paths.forEach(path { const [module, field] path.split(/) const target module ? store.state[module] : store.state if (saved[path] ! undefined) { target[field] saved[path] } }) } catch (e) { localStorage.removeItem(KEY) } } // 保存做節(jié)流避免頻繁寫入 let timer null store.subscribe((mutation, state) { clearTimeout(timer) timer setTimeout(() { const data {} paths.forEach(path { const [module, field] path.split(/) const target module ? state[module] : state data[path] target?.[field] }) localStorage.setItem(KEY, JSON.stringify(data)) }, 300) }) } }用它的時候只白名單需要的字段createStore({ plugins: [createPersistPlugin([user/token, cart/items])] })為什么只白名單而不是全量存因為submitting、loading這類瞬時狀態(tài)被持久化下來刷新頁面后按鈕會一直處于 loading 狀態(tài)用戶以為卡死了。我見過一個項目把整個 store 都存了 localStorage結果用戶重新打開頁面上次沒提交完的表單數據混著新數據出現(xiàn)問題反饋了一堆。4. 高頻踩坑與排查實錄4.1 報錯信息對照表先會看再看懂Vuex 的報錯信息其實寫得挺清楚只是新手不知道往哪查。整理一張表遇到問題先對號入座報錯內容大概率原因處理方式[vuex] unknown mutation type: xxx模塊沒開 namespaced或漏寫模塊前綴檢查模塊配置commit 時補上模塊名/[vuex] unknown action type: xxx跨模塊調用漏了{ root: true }dispatch 第三個參數加上 root[vuex] unknown getter: xxxgetters 沒導出或訪問路徑錯確認 export default 里有 gettersdo not mutate vuex store state outside mutation handlers開發(fā)環(huán)境嚴格模式直接改了 state把所有賦值搬進 mutation[vuex] module namespace not found in mapState()模塊名拼錯或模塊還沒注冊檢查 createStore 的 modules 鍵名Cannot read property xxx of undefined模塊 state 寫成了對象但被復用state 改成函數返回數據改了但頁面沒更新直接改數組下標或對象新增屬性用 mutation 里整體替換或Vue.setVue 2這張表我自己貼在工位旁邊貼了兩年新人來的時候直接拍照。說實話Vuex 報錯里 80% 都是“路徑寫錯”或者“沒開命名空間”這兩類剩下 20% 是響應式丟失。4.2 響應式丟失的幾種典型情況Vue 2 時代最經典的問題state.list[0] newItem頁面不更新。原因是Object.defineProperty攔截不到數組下標賦值。Vue 3 換成 Proxy 之后這個問題基本解決了但如果你維護的是 Vue 2 Vuex 3 的項目還是得注意數組按下標賦值用splice或者整體替換數組對象新增屬性用Vue.set(obj, key, val)刪除屬性用Vue.delete(obj, key)Vue 3 里雖然 Proxy 能攔截新增和刪除但還是有兩個容易忽略的點。一是reactive對象被解構之后失去響應式比如const { profile } store.state.user后面profile就是普通對象了怎么改頁面都不動。二是把 state 里的對象直接賦給組件里的變量做雙向綁定v-model一改就直接改了 state繞過 mutation開發(fā)環(huán)境立刻報嚴格模式錯誤。正確的v-model寫法是這樣computed: { keyword: { get() { return this.$store.state.cart.keyword }, set(val) { this.$store.commit(cart/SET_KEYWORD, val) } } }啰嗦是啰嗦但這條鏈路是完整的devtools 能記錄到每一次輸入。如果嫌麻煩就在組件內用本地 ref提交時再一次性寫回 store。4.3 性能問題什么時候 store 成了瓶頸Vuex 的性能問題我遇到過的就那么幾類但每一類都很要命。第一類是大列表全量放進 store。有個項目把五千條訂單數據放在 state 里每次篩選都要經過 getter頁面卡得沒法用。后來改成 store 只存篩選條件列表數據留在組件里通過 action 拿問題立刻解決。記住store 適合存“狀態(tài)”不適合存“數據集合”。第二類是在 getter 里做重計算。比如對列表做排序、格式化日期、算分組小計這些操作如果依賴頻繁變化getter 會被反復觸發(fā)。我的做法是把這類計算移到組件 computed或者在 store 里緩存一份計算結果只在源數據變化時重算。第三類是過度訂閱。mapState把整個模塊的 state 都映射進來其中某個字段高頻變化導致組件整體重新渲染。用computed精確取需要的字段能緩解一部分更好的辦法是把高頻變化的狀態(tài)比如輸入框的值、鼠標坐標留在組件本地不要進 store。還有一種不太容易發(fā)現(xiàn)的devtools 開著跑生產構建。Vuex 的 devtools 集成在開發(fā)模式下才有但如果你不小心在生產包里引入了開發(fā)版本的 Vue性能會差好幾倍。打包配置里確認一下mode和define有沒有問題這個坑我踩過一次找了一周。4.4 老項目遷移與工程化建議如果手上的 Vuex 項目要重構我建議按這個順序推進別一把梭。第一步先把所有this.$store的直接調用收斂成統(tǒng)一的 API 層。寫一個src/store/api.js把常用的讀寫封裝成函數比如useUser()、useCart()。這一步不改邏輯只是加一層殼風險極低。第二步把模塊的 mutation 命名規(guī)范化。原來可能叫setUser、updateUser、changeUser統(tǒng)一成SET_USER。這一步靠grep加人工核對工作量不大但收益明顯后面遷移 Pinia 時一一對應就能改。第三步按模塊遷移。先挑一個依賴最少的模塊比如cart改成 Pinia 的defineStore然后在入口同時注冊兩套。Vuex 和 Pinia 是可以共存的只要別讓同一個業(yè)務狀態(tài)兩邊都存就行。第四步清理。所有模塊遷完之后刪掉 Vuex 依賴把mapState之類的 import 全部替換。這一步用 ESLint 的自定義規(guī)則能掃出一部分剩下的靠編譯報錯兜底。遷移過程中有個細節(jié)值得說Pinia 的storeToRefs和 Vuex 的toRefs行為不完全一樣直接在組件里解構很容易出問題。我當時的做法是先把所有組件里的解構都改成computed遷完之后再按需優(yōu)化。寧可多寫幾行也別在響應式上翻車。5. 幾個真實場景下的套路組合5.1 登錄態(tài)與路由守衛(wèi)的配合登錄態(tài)是最典型的需要 store 的場景但它和路由守衛(wèi)的配合有個時序問題必須處理。守衛(wèi)在頁面渲染前執(zhí)行這時候如果 store 里的用戶信息還沒加載權限判斷就會失敗用戶被誤踢回登錄頁。我的處理方式是token 從 localStorage 同步恢復用戶信息異步加載但守衛(wèi)里做“是否已加載”的判斷沒加載就先觸發(fā) action 并等待。// permission.js router.beforeEach(async (to, from, next) { const store useStore() const token store.state.user.token if (!token) { return to.meta.public ? next() : next({ path: /login, query: { redirect: to.fullPath } }) } if (!store.state.user.permissionLoaded) { try { await store.dispatch(user/fetchProfile) await store.dispatch(permission/loadRoutes) } catch (e) { store.commit(user/RESET) return next(/login) } } if (to.meta.roles !store.getters[user/hasPermission](to.meta.roles)) { return next(/403) } next() })這里的關鍵是permissionLoaded這個標記位。沒有它每次路由跳轉都要重新拉一次用戶信息接口壓力大不說頁面還會閃。有了它第一次加載完之后所有跳轉都是同步判斷體驗就順了。異步路由用router.addRoute動態(tài)注冊注冊完再next({ ...to, replace: true })重新進入一次否則會白屏。5.2 跨模塊協(xié)作別讓模塊之間互相 import項目一大模塊之間必然有協(xié)作。比如下單成功后要清空購物車、刷新訂單列表、更新用戶積分。這三件事分屬三個模塊怎么串起來最差的做法是在order模塊里import cart from ./cart然后直接調。這樣寫會形成循環(huán)依賴打包時可能報錯運行時也可能拿到 undefined。正確做法是通過 action 互相 dispatch// order 模塊的 action async createOrder({ commit, dispatch }, payload) { const res await api.createOrder(payload) commit(ADD_ORDER, res.data) // 跨模塊通知各自處理各自的邏輯 await dispatch(cart/clearChecked, null, { root: true }) await dispatch(user/refreshPoints, null, { root: true }) return res.data }這樣order模塊不需要知道cart內部怎么實現(xiàn)只要知道有這么個 action 就行。耦合度低測試也好寫。如果模塊數量多、協(xié)作關系復雜可以再引入一個“編排層”專門寫跨模塊的 action把業(yè)務流程集中在一處。還有個小技巧跨模塊讀取數據用 getters不要直接讀rootState.xxx.yyy。getters 是一層抽象將來內部結構變了只要 getter 的返回不變調用方就不用改。5.3 表單草稿和列表緩存的取舍后臺系統(tǒng)里最常見的兩個需求表單填一半切走了回來要恢復列表翻到第五頁點進詳情再返回要停在第五頁。表單草稿我的做法是不進 store用sessionStorage加組件內的watch做防抖保存。原因很簡單草稿是頁面級的狀態(tài)多個表單同時編輯時放 store 會互相干擾還要處理各種清理邏輯。sessionStorage 天然按標簽頁隔離關掉就沒了符合直覺。列表緩存反而適合進 store。因為篩選條件、頁碼、排序方式這些是需要跨路由保留的而且詳情頁返回時要用。做法是在list模塊里存一份query對象列表頁onMounted時讀出來發(fā)起請求條件變化時同步更新。要注意的是從菜單重新點進列表時應該重置從詳情返回時應該保留這個區(qū)分靠路由的meta.keepAlive或者判斷from路徑來做。const actions { async loadList({ state, commit }, { reset false } {}) { if (reset) { commit(RESET_QUERY) } const res await api.getList(state.query) commit(SET_LIST, res.data) } }reset參數由調用方決定模塊本身不猜。這種“讓調用方明確表達意圖”的設計比在模塊里寫一堆 if 判斷當前路由要清晰得多。6. 我個人在實際項目里的幾點體會寫到這里Vuex 的主要知識點基本都覆蓋了。最后分享幾個不太適合寫進文檔、但實際干活時確實管用的經驗。第一別怕寫重復代碼。Vuex 的四段式state/getters/mutations/actions看起來很啰嗦但每多寫一行將來排查問題時就少猜一次。我曾經為了省事把 mutation 和 action 合并成一個函數結果 devtools 里全是匿名調用出問題時完全不知道是誰改的。后來老老實實拆開調試效率反而高了。第二給 store 加注釋比加文檔有用。每個模塊文件頂部寫清楚這個模塊管什么、依賴誰、被誰依賴比單獨維護一份文檔靠譜得多。文檔會過期代碼不會。我現(xiàn)在接手新項目第一件事就是看 store 模塊的頂部注釋五分鐘就能摸清業(yè)務脈絡。第三調試時善用 devtools 的 import/export。Vuex 面板可以把當前狀態(tài)導出成 JSON也能導入一份狀態(tài)來復現(xiàn)問題。遇到用戶反饋的詭異 bug讓對方導出一份狀態(tài)文件本地導入后就能完全復現(xiàn)當時的場景比反復溝通效率高太多。這個功能知道的人不多但真的好用。第四測試只測 action 和 getter。state 和 mutation 太簡單測了也是形式主義。真正有價值的是 action 里的業(yè)務流程和 getter 里的計算邏輯這兩塊寫單測覆蓋率能上一個大臺階。測 action 的時候記得 mock 掉commit和dispatch用jest.fn()或者vi.fn()都行斷言調用參數就夠了。最后提一句狀態(tài)管理這塊工具會換但“什么狀態(tài)該放在哪一層、變更走什么路徑、如何保證可追溯”這三個問題不會變。把 Vuex 這套東西吃透換成 Pinia、換成任何別的方案思路都是通用的。 Vuex 4 狀態(tài)管理全解析：核心原理、模塊拆分與高頻踩坑
Vuex 這玩意兒現(xiàn)在提起來有點微妙。新項目里 Pinia 基本是默認選項很多人一上手 Vue 3 就沒碰過 Vuex。但你去翻一翻手上維護的那些跑了三四年的中后臺系統(tǒng)十有八九還在store/index.js里躺著幾十個 mutation改一個字段要先找 action、再找 mutation、最后才敢動 state。這時候你要是連 Vuex 的執(zhí)行鏈路都說不清楚排查問題基本靠猜。這篇就把 Vuex 的知識點掰開揉碎講透從“到底什么時候該用它”到“store 怎么拆模塊”再到“為什么我的 commit 沒生效”這類真實踩坑全部過一遍。適合兩類人看一類是剛接手老項目、被mapState和各種root: true繞暈的新手另一類是想把狀態(tài)管理這塊徹底搞清楚、以后不管換 Pinia 還是別的庫都能快速上手的同學。代碼以 Vuex 4 Vue 3 為主線涉及 Vue 2 的差異我會單獨標出來。1. 先搞清楚什么時候真的需要 Vuex1.1 狀態(tài)管理的邊界到底在哪我在帶人的時候發(fā)現(xiàn)一個特別普遍的問題很多人學完 Vuex 的第一反應是“好東西全塞進去”。結果一個只有三個頁面的小工具store 里堆了二十多個字段其中一半是某個組件內部的彈窗開關。這就屬于把狀態(tài)管理當成了全局變量倉庫最后維護成本比不用還高。判斷一個狀態(tài)該不該進 store我一般看三條第一這份數據是不是被兩個以上互不相鄰的組件同時使用。父子組件之間傳值props加emit就夠了爺孫層級深一點provide/inject也能解決。只有當兄弟組件、或者跨了好幾層的遠房親戚都要讀寫同一份數據時才輪到 Vuex 出場。第二這份數據是不是跨越了路由。比如登錄態(tài)、用戶信息、權限菜單從 A 頁面跳到 B 頁面還得用這種放在組件里必然會隨著組件銷毀而丟失必須提上去。第三這份數據變更后是不是需要留下可追溯的痕跡。Vuex 配 devtools 能記錄每一次 mutation 的時間旅行對于復雜的表單聯(lián)動、購物車增刪改這個調試能力值不少時間。反過來說哪些不該進 store組件的 loading 狀態(tài)、某個列表的滾動位置、彈窗的顯隱開關這些都屬于“局部狀態(tài)”跟著組件生命周期走才是最干凈的。我見過有人把dialogVisible放進 store結果兩個頁面復用同一個彈窗組件時互相干擾排查了半天才發(fā)現(xiàn)是狀態(tài)被共享了。記住一句話狀態(tài)放得越高耦合就越重能不升就不升。還有一種常見誤區(qū)是把接口返回的原始數據全量塞進 store然后組件里再filter一遍。這樣做的問題在于 store 變成了緩存層但你又沒做失效策略最后數據新舊不一致的 bug 特別難查。我的習慣是 store 只存“經過業(yè)務加工、有明確語義”的狀態(tài)原始響應體在 action 里處理完就丟掉。1.2 Vuex 和 Pinia 到底怎么選這個話題繞不開。Pinia 確實是官方現(xiàn)在主推的方案API 更簡潔、TypeScript 支持更好、沒有 mutation 這一層。但“新項目用 Pinia”不等于“Vuex 就沒用了”。我整理了一張對照表你對著自己項目的情況看就行。對比維度Vuex 4Pinia變更入口mutation 提交action 觸發(fā)直接改 stateaction 里也能改模塊機制modules namespaced 嵌套每個 store 天然獨立TypeScript 支持需要額外類型聲明較繁瑣原生推導幾乎零配置devtools 時間旅行支持粒度到 mutation支持粒度到 action代碼量一個功能要寫 state/getter/mutation/action 四份基本一份 setup 或 option 就夠學習曲線概念多鏈路長概念少接近組合式函數存量項目兼容原生可與 Vuex 共存逐模塊遷移適合場景老項目維護、團隊已有約定新項目、TS 重度使用我的實際經驗是已經在跑的 Vuex 項目別為了追新去動它。遷移本身不難難的是遷移期間兩套狀態(tài)管理并存帶來的心智負擔以及測試覆蓋不足時的回歸風險。真要遷也是按模塊一個個搬先把用戶模塊搬過去跑一周沒問題再搬下一個。反倒是新起的項目沒有歷史包袱直接上 Pinia 更省事。不過有一點要說清楚Vuex 那套“mutation 必須同步、action 處理異步”的約束雖然寫起來啰嗦但它強迫你把“改數據”和“做業(yè)務”分開這個思維在團隊協(xié)作里是有價值的。很多 Pinia 新手直接在 action 里一頓this.xxx yyy出了問題連是哪一步改的都定位不到。所以就算你用的是 Pinia也建議保留“純函數式改狀態(tài)”的習慣。1.3 一張判斷清單幫你決定要不要引入我給自己團隊寫過一個很土但很好用的清單五個問題中三個以上才考慮上 Vuex有沒有一份數據被三個以上的組件讀取且這些組件不在同一條父子鏈上這份數據會不會因為路由切換而需要保留這份數據的修改是否需要多人協(xié)作、且改動點分散在多個文件出問題時是否需要回放“誰在什么時候改了什么”項目規(guī)模是不是已經超過二十個頁面或者五個以上的業(yè)務模塊如果只中一兩條老老實實用props加組合式函數封裝別給自己找事。狀態(tài)管理的本質是降低溝通成本不是炫技。2. Vuex 的五個核心概念一次捋直2.1 state單一狀態(tài)樹和它的設計原則Vuex 把所有狀態(tài)收攏到一棵樹里官方叫單一狀態(tài)樹Single Source of Truth。好處是任何一個時刻你都能通過store.state拿到應用完整的數據快照調試的時候特別直觀。壞處是這棵樹如果沒人管長到幾百個字段之后新人進來根本看不懂哪個字段屬于哪個業(yè)務。我的做法是按業(yè)務域切分而不是按數據類型切分。什么叫按數據類型切就是state.list、state.detail、state.loading這么平鋪看著整齊實際上一旦業(yè)務變多就全亂。按業(yè)務域切就是user、order、permission各占一塊每個模塊自洽。具體到寫法Vuex 4 里定義模塊的 state 一定要用函數返回對象// store/modules/user.js const state () ({ profile: null, token: , roles: [], permissionLoaded: false })為什么必須是函數因為模塊在注冊時會被合并進根 state如果直接寫對象字面量多個組件實例或者熱更新場景下會共享同一份引用出現(xiàn)“A 頁面改了 B 頁面也變了”的靈異事件。這個坑我在服務端渲染的項目里踩過一次排查了整整一個下午。另外 state 里的字段命名要帶語義。data、info、list這種詞盡量別用orderList、userProfile、pendingTaskCount一眼就知道是什么。字段一多命名就是最好的文檔。2.2 getters派生狀態(tài)和它的緩存機制getters 可以理解為 store 里的 computed。它的返回值會基于依賴做緩存依賴不變就不重新計算。這個特性用好了能省不少性能用不好反而會成為 bug 來源。const getters { isLogin: state Boolean(state.token), displayName: state state.profile?.nickname || state.profile?.username || 未登錄, // 依賴其他 getter第二個參數是當前模塊的 getters welcomeText: (state, getters) ${getters.displayName}歡迎回來, // 依賴根 state第四個參數是 rootState hasPermission: (state, getters, rootState) code { return state.roles.includes(code) || rootState.user.roles.includes(code) } }這里有個關鍵點getter 返回函數時緩存就失效了。上面hasPermission返回的是一個函數每次調用都會重新執(zhí)行因為 Vue 沒法追蹤函數內部用到的參數。這種寫法適合做權限判斷這類需要傳參的場景但別在模板里高頻調用它尤其是列表渲染里v-for每一項都調一次性能會明顯下降。真要這么用先在 computed 里把結果算好。還有一個容易翻車的地方getter 里返回新對象。比如// 不推薦每次都返回新數組緩存形同虛設 filteredList: state state.list.filter(item item.active)因為filter每次執(zhí)行都會產生新數組引用Vue 的依賴追蹤會認為結果變了導致依賴這個 getter 的組件反復更新。如果這個列表很大、更新又頻繁頁面會明顯卡頓。正確做法是把過濾邏輯放到組件 computed 里或者用shallowRef之類的思路做手動緩存。我在一個萬級數據的表格項目里就吃過這個虧后來把 getter 改成了只做簡單映射流暢度立刻回來了。2.3 mutations為什么它必須是同步的這是 Vuex 里被問得最多的問題?！拔揖驮?mutation 里發(fā)個請求怎么了”答案藏在 devtools 的工作原理里。devtools 記錄狀態(tài)變化的方式是每執(zhí)行一次 mutation就拍一張 state 的快照存進時間線。如果你在 mutation 里發(fā)異步請求那么“mutation 開始執(zhí)行”和“state 真正被改”之間存在時間差devtools 拍到的那張快照可能是請求還沒回來的中間態(tài)。等你點時間旅行回到某一步看到的狀態(tài)和實際不符調試就徹底失去了意義。所以 Vuex 強制 mutation 同步是為了保證每一幀快照都是確定性的。const mutations { SET_PROFILE(state, payload) { state.profile payload }, SET_TOKEN(state, token) { state.token token }, ADD_ROLE(state, role) { if (!state.roles.includes(role)) { state.roles.push(role) } }, RESET(state) { // 重置時不要直接替換整個 state 對象Vue 會丟失響應式追蹤 Object.assign(state, { profile: null, token: , roles: [], permissionLoaded: false }) } }mutation 的命名我統(tǒng)一用全大寫加下劃線這是社區(qū)慣例好處是在 devtools 列表里一眼就能和 action 區(qū)分開。action 用小駝峰比如fetchProfile。這套約定看起來是小事但團隊人多的時候能省掉很多溝通。還有一個細節(jié)mutation 里不要做副作用。什么叫副作用發(fā)請求、寫 localStorage、彈 toast這些都算。mutation 應該是一個純函數給它同樣的輸入state 就變成同樣的結果。這樣你寫單元測試的時候只需要斷言 state 變化不用 mock 一堆東西。2.4 actions異步編排和業(yè)務邏輯的落腳點action 是 Vuex 里唯一允許寫異步的地方它不直接改 state而是通過commit觸發(fā) mutation。這個設計看起來多繞了一層實際上把“業(yè)務流程”和“數據變更”解耦了。const actions { async fetchProfile({ commit, state, dispatch }, force false) { if (state.profile !force) { return state.profile } const res await api.getUserProfile() commit(SET_PROFILE, res.data) // 跨模塊調用要加 root: true await dispatch(permission/loadRoutes, res.data.roles, { root: true }) return res.data }, async login({ commit, dispatch }, { username, password }) { const { token } await api.login({ username, password }) commit(SET_TOKEN, token) await dispatch(fetchProfile, true) }, logout({ commit }) { commit(RESET) commit(permission/RESET, null, { root: true }) } }action 的返回值很重要。因為 action 內部是 Promise你可以在組件里await store.dispatch(login, form)拿到結果后再做跳轉或者提示。很多老代碼里 action 不 return組件只能靠 watch 某個 state 來判斷成功與否這種寫法非常脆弱。養(yǎng)成習慣action 有結果就 return 出去?？缒K dispatch 的{ root: true }是新手最容易漏的參數。不加這個參數Vuex 會只在當前模塊內查找 action找不到就靜默失敗或者報unknown action type。我第一次遇到的時候盯著代碼看了半小時最后發(fā)現(xiàn)就是少了個 root。2.5 modules 和 namespaced拆分與隔離項目一大單文件 store 必然爆炸。modules 就是用來拆的而namespaced: true決定了拆完之后彼此是否隔離。// store/index.js import { createStore } from vuex import user from ./modules/user import permission from ./modules/permission import cart from ./modules/cart export default createStore({ strict: import.meta.env.DEV, modules: { user: { namespaced: true, ...user }, permission: { namespaced: true, ...permission }, cart: { namespaced: true, ...cart } } })開不開命名空間我的答案是業(yè)務模塊一律開。不開的話所有模塊的 mutation 都注冊在全局兩個模塊都定義了SET_LOADING后注冊的會覆蓋前一個這種 bug 隱蔽性極強。開了之后方法名變成user/SET_LOADING雖然寫起來長一點但邊界清晰。全局的通用狀態(tài)比如 app 級別的主題、語言可以單開一個不開命名空間的 root 模塊但數量要克制。嵌套模塊的調用鏈路也要理清楚。假設有個setting模塊掛在user下面那么在setting的 action 里調用兄弟模塊路徑要寫成dispatch(cart/addItem, item, { root: true })。這個 root 參數指的是“從根開始找”不管你現(xiàn)在在哪一層。記不住的話就記一句只要跨出當前模塊就帶 root: true。3. 從零搭一個能落地的 Store 結構3.1 目錄設計和模塊拆分原則先看目錄這是我用了幾年、覺得最不容易亂的一種src/ ├── store/ │ ├── index.js // 入口注冊模塊和插件 │ ├── plugins/ │ │ └── persist.js // 持久化插件 │ ├── modules/ │ │ ├── user.js // 用戶信息、登錄態(tài) │ │ ├── permission.js // 路由權限、菜單 │ │ └── cart.js // 業(yè)務模塊示例 │ └── helpers.js // 通用工具比如生成 mutation types拆分粒度怎么定我的一般原則是一個模塊對應一個業(yè)務域而不是一個頁面。比如訂單列表和訂單詳情都屬于 order 模塊不要拆成兩個。反過來用戶和權限雖然是相關的但職責不同用戶管“我是誰”權限管“我能看什么”拆開更好維護。模塊內部的結構我習慣按state → getters → mutations → actions → 導出的順序寫和 Vuex 的執(zhí)行鏈路一致讀代碼的人從上往下看正好是數據流向。文件末尾統(tǒng)一導出export default { namespaced: true, state, getters, mutations, actions }有一點要注意如果模塊之間有數據依賴不要在模塊文件里直接import另一個模塊的 state那樣會造成循環(huán)依賴。正確方式是通過rootState讀取或者用dispatch讓對方的 action 來處理。3.2 完整實現(xiàn)一個購物車模塊光說概念沒意思直接上一個能跑的。假設我們要做一個購物車需求是加商品、改數量、刪除、算總價、選中狀態(tài)管理。// store/modules/cart.js const state () ({ items: [], // { id, name, price, count, checked } submitting: false }) const getters { totalCount: state state.items.reduce((sum, i) sum i.count, 0), checkedItems: state state.items.filter(i i.checked), totalPrice: (state, getters) { // 金額用分做單位避免浮點誤差最后再除以 100 const cents getters.checkedItems.reduce((sum, i) sum i.price * 100 * i.count, 0) return cents / 100 }, isAllChecked: state state.items.length 0 state.items.every(i i.checked) } const mutations { ADD_ITEM(state, product) { const exist state.items.find(i i.id product.id) if (exist) { exist.count 1 } else { state.items.push({ ...product, count: 1, checked: true }) } }, UPDATE_COUNT(state, { id, count }) { const item state.items.find(i i.id id) if (item) { item.count Math.max(1, Math.min(99, count)) } }, TOGGLE_CHECK(state, id) { const item state.items.find(i i.id id) if (item) item.checked !item.checked }, TOGGLE_ALL(state, checked) { state.items.forEach(i { i.checked checked }) }, REMOVE_ITEM(state, id) { state.items state.items.filter(i i.id ! id) }, SET_SUBMITTING(state, flag) { state.submitting flag }, CLEAR(state) { state.items [] } } const actions { async checkout({ commit, state, rootState }) { if (!state.items.length) return { ok: false, msg: 購物車是空的 } const payload state.items .filter(i i.checked) .map(i ({ productId: i.id, count: i.count })) commit(SET_SUBMITTING, true) try { const res await api.submitOrder({ items: payload, userId: rootState.user.profile?.id }) commit(REMOVE_ITEM_BATCH, res.data.removedIds) return { ok: true, orderId: res.data.orderId } } catch (e) { return { ok: false, msg: e.message } } finally { commit(SET_SUBMITTING, false) } } } export default { namespaced: true, state, getters, mutations, actions }這里有幾個我自己踩過坑之后固定下來的寫法。金額全部用“分”來算最后展示時再轉回元0.1 0.2那種經典浮點問題在電商場景真的會出事。數量做了Math.max(1, Math.min(99, count))的鉗制防止用戶在輸入框里手打負號或者超大批量。checkout的返回值統(tǒng)一成{ ok, msg }結構組件層不用 try-catch直接看ok就行。另外REMOVE_ITEM_BATCH我在 mutations 里沒寫實際項目中應該補上避免循環(huán)提交單條刪除。這類細節(jié)在真實業(yè)務里會因為批量操作導致幾十次 commitdevtools 面板直接被刷屏。3.3 組件里怎么調用四種方式對比Vuex 提供的調用方式有好幾種很多人只會mapState遇到方法就不知道咋辦了。列個表對照著記場景選項式寫法組合式寫法setup讀 statecomputed(() this.$store.state.user.profile)const profile computed(() store.state.user.profile)讀 getterthis.$store.getters[user/isLogin]computed(() store.getters[user/isLogin])觸發(fā) mutationthis.$store.commit(user/SET_TOKEN, t)store.commit(user/SET_TOKEN, t)觸發(fā) actionawait this.$store.dispatch(user/login, f)await store.dispatch(user/login, f)批量映射...mapState(user, [profile])storeToRefs(store.state.user)配合解構組合式 API 里推薦用useStore加storeToRefsimport { computed } from vue import { useStore } from vuex import { storeToRefs } from pinia // 注意Vuex 沒有官方 storeToRefs這里用 toRefs 替代 export default { setup() { const store useStore() // 直接解構會丟失響應式必須轉成 ref const { profile, token } toRefs(store.state.user) const isLogin computed(() store.getters[user/isLogin]) function handleAdd(product) { store.commit(cart/ADD_ITEM, product) } return { profile, token, isLogin, handleAdd } } }補充一句上面代碼里storeToRefs是 Pinia 的 APIVuex 項目要用 Vue 的toRefs配合store.state.模塊名。這個區(qū)別我見過不止一個人寫混。toRefs只能處理普通響應式對象store.state本身就是響應式的所以能用但store.getters不行因為 getters 是每次訪問時動態(tài)計算的得用computed包一層。選項式 API 里用輔助函數會簡潔很多import { mapState, mapGetters, mapActions } from vuex export default { computed: { ...mapState(cart, [items, submitting]), ...mapGetters(cart, [totalPrice, isAllChecked]), // 自己再算的派生值 isEmpty() { return this.items.length 0 } }, methods: { ...mapActions(cart, [checkout]), async onSubmit() { const res await this.checkout() if (res.ok) { // 跳轉邏輯 } } } }有個小坑要提醒mapState映射出來的名字如果和組件data里的字段重名Vue 會告警而且行為不確定。命名的時候盡量錯開或者在映射時用對象形式重命名...mapState(cart, { cartItems: items })。3.4 嚴格模式、持久化插件和 devtools 配置嚴格模式我強烈建議只在開發(fā)環(huán)境開const store createStore({ strict: import.meta.env.DEV, modules: { ... } })嚴格模式下任何不經過 mutation 的 state 修改都會拋錯[vuex] do not mutate vuex store state outside mutation handlers。這個檢查很耗性能因為它需要深度監(jiān)聽整棵 state 樹。生產環(huán)境開嚴格模式在大型應用里能明顯感覺到卡頓。用 Vite 的話import.meta.env.DEV就是現(xiàn)成的webpack 環(huán)境用process.env.NODE_ENV ! production。持久化這塊Vuex 本身不提供社區(qū)有插件但也都不太維護了我一般手寫一個三十行的插件// store/plugins/persist.js const KEY APP_STORE_V1 export default function createPersistPlugin(paths []) { return store { // 恢復 const raw localStorage.getItem(KEY) if (raw) { try { const saved JSON.parse(raw) paths.forEach(path { const [module, field] path.split(/) const target module ? store.state[module] : store.state if (saved[path] ! undefined) { target[field] saved[path] } }) } catch (e) { localStorage.removeItem(KEY) } } // 保存做節(jié)流避免頻繁寫入 let timer null store.subscribe((mutation, state) { clearTimeout(timer) timer setTimeout(() { const data {} paths.forEach(path { const [module, field] path.split(/) const target module ? state[module] : state data[path] target?.[field] }) localStorage.setItem(KEY, JSON.stringify(data)) }, 300) }) } }用它的時候只白名單需要的字段createStore({ plugins: [createPersistPlugin([user/token, cart/items])] })為什么只白名單而不是全量存因為submitting、loading這類瞬時狀態(tài)被持久化下來刷新頁面后按鈕會一直處于 loading 狀態(tài)用戶以為卡死了。我見過一個項目把整個 store 都存了 localStorage結果用戶重新打開頁面上次沒提交完的表單數據混著新數據出現(xiàn)問題反饋了一堆。4. 高頻踩坑與排查實錄4.1 報錯信息對照表先會看再看懂Vuex 的報錯信息其實寫得挺清楚只是新手不知道往哪查。整理一張表遇到問題先對號入座報錯內容大概率原因處理方式[vuex] unknown mutation type: xxx模塊沒開 namespaced或漏寫模塊前綴檢查模塊配置commit 時補上模塊名/[vuex] unknown action type: xxx跨模塊調用漏了{ root: true }dispatch 第三個參數加上 root[vuex] unknown getter: xxxgetters 沒導出或訪問路徑錯確認 export default 里有 gettersdo not mutate vuex store state outside mutation handlers開發(fā)環(huán)境嚴格模式直接改了 state把所有賦值搬進 mutation[vuex] module namespace not found in mapState()模塊名拼錯或模塊還沒注冊檢查 createStore 的 modules 鍵名Cannot read property xxx of undefined模塊 state 寫成了對象但被復用state 改成函數返回數據改了但頁面沒更新直接改數組下標或對象新增屬性用 mutation 里整體替換或Vue.setVue 2這張表我自己貼在工位旁邊貼了兩年新人來的時候直接拍照。說實話Vuex 報錯里 80% 都是“路徑寫錯”或者“沒開命名空間”這兩類剩下 20% 是響應式丟失。4.2 響應式丟失的幾種典型情況Vue 2 時代最經典的問題state.list[0] newItem頁面不更新。原因是Object.defineProperty攔截不到數組下標賦值。Vue 3 換成 Proxy 之后這個問題基本解決了但如果你維護的是 Vue 2 Vuex 3 的項目還是得注意數組按下標賦值用splice或者整體替換數組對象新增屬性用Vue.set(obj, key, val)刪除屬性用Vue.delete(obj, key)Vue 3 里雖然 Proxy 能攔截新增和刪除但還是有兩個容易忽略的點。一是reactive對象被解構之后失去響應式比如const { profile } store.state.user后面profile就是普通對象了怎么改頁面都不動。二是把 state 里的對象直接賦給組件里的變量做雙向綁定v-model一改就直接改了 state繞過 mutation開發(fā)環(huán)境立刻報嚴格模式錯誤。正確的v-model寫法是這樣computed: { keyword: { get() { return this.$store.state.cart.keyword }, set(val) { this.$store.commit(cart/SET_KEYWORD, val) } } }啰嗦是啰嗦但這條鏈路是完整的devtools 能記錄到每一次輸入。如果嫌麻煩就在組件內用本地 ref提交時再一次性寫回 store。4.3 性能問題什么時候 store 成了瓶頸Vuex 的性能問題我遇到過的就那么幾類但每一類都很要命。第一類是大列表全量放進 store。有個項目把五千條訂單數據放在 state 里每次篩選都要經過 getter頁面卡得沒法用。后來改成 store 只存篩選條件列表數據留在組件里通過 action 拿問題立刻解決。記住store 適合存“狀態(tài)”不適合存“數據集合”。第二類是在 getter 里做重計算。比如對列表做排序、格式化日期、算分組小計這些操作如果依賴頻繁變化getter 會被反復觸發(fā)。我的做法是把這類計算移到組件 computed或者在 store 里緩存一份計算結果只在源數據變化時重算。第三類是過度訂閱。mapState把整個模塊的 state 都映射進來其中某個字段高頻變化導致組件整體重新渲染。用computed精確取需要的字段能緩解一部分更好的辦法是把高頻變化的狀態(tài)比如輸入框的值、鼠標坐標留在組件本地不要進 store。還有一種不太容易發(fā)現(xiàn)的devtools 開著跑生產構建。Vuex 的 devtools 集成在開發(fā)模式下才有但如果你不小心在生產包里引入了開發(fā)版本的 Vue性能會差好幾倍。打包配置里確認一下mode和define有沒有問題這個坑我踩過一次找了一周。4.4 老項目遷移與工程化建議如果手上的 Vuex 項目要重構我建議按這個順序推進別一把梭。第一步先把所有this.$store的直接調用收斂成統(tǒng)一的 API 層。寫一個src/store/api.js把常用的讀寫封裝成函數比如useUser()、useCart()。這一步不改邏輯只是加一層殼風險極低。第二步把模塊的 mutation 命名規(guī)范化。原來可能叫setUser、updateUser、changeUser統(tǒng)一成SET_USER。這一步靠grep加人工核對工作量不大但收益明顯后面遷移 Pinia 時一一對應就能改。第三步按模塊遷移。先挑一個依賴最少的模塊比如cart改成 Pinia 的defineStore然后在入口同時注冊兩套。Vuex 和 Pinia 是可以共存的只要別讓同一個業(yè)務狀態(tài)兩邊都存就行。第四步清理。所有模塊遷完之后刪掉 Vuex 依賴把mapState之類的 import 全部替換。這一步用 ESLint 的自定義規(guī)則能掃出一部分剩下的靠編譯報錯兜底。遷移過程中有個細節(jié)值得說Pinia 的storeToRefs和 Vuex 的toRefs行為不完全一樣直接在組件里解構很容易出問題。我當時的做法是先把所有組件里的解構都改成computed遷完之后再按需優(yōu)化。寧可多寫幾行也別在響應式上翻車。5. 幾個真實場景下的套路組合5.1 登錄態(tài)與路由守衛(wèi)的配合登錄態(tài)是最典型的需要 store 的場景但它和路由守衛(wèi)的配合有個時序問題必須處理。守衛(wèi)在頁面渲染前執(zhí)行這時候如果 store 里的用戶信息還沒加載權限判斷就會失敗用戶被誤踢回登錄頁。我的處理方式是token 從 localStorage 同步恢復用戶信息異步加載但守衛(wèi)里做“是否已加載”的判斷沒加載就先觸發(fā) action 并等待。// permission.js router.beforeEach(async (to, from, next) { const store useStore() const token store.state.user.token if (!token) { return to.meta.public ? next() : next({ path: /login, query: { redirect: to.fullPath } }) } if (!store.state.user.permissionLoaded) { try { await store.dispatch(user/fetchProfile) await store.dispatch(permission/loadRoutes) } catch (e) { store.commit(user/RESET) return next(/login) } } if (to.meta.roles !store.getters[user/hasPermission](to.meta.roles)) { return next(/403) } next() })這里的關鍵是permissionLoaded這個標記位。沒有它每次路由跳轉都要重新拉一次用戶信息接口壓力大不說頁面還會閃。有了它第一次加載完之后所有跳轉都是同步判斷體驗就順了。異步路由用router.addRoute動態(tài)注冊注冊完再next({ ...to, replace: true })重新進入一次否則會白屏。5.2 跨模塊協(xié)作別讓模塊之間互相 import項目一大模塊之間必然有協(xié)作。比如下單成功后要清空購物車、刷新訂單列表、更新用戶積分。這三件事分屬三個模塊怎么串起來最差的做法是在order模塊里import cart from ./cart然后直接調。這樣寫會形成循環(huán)依賴打包時可能報錯運行時也可能拿到 undefined。正確做法是通過 action 互相 dispatch// order 模塊的 action async createOrder({ commit, dispatch }, payload) { const res await api.createOrder(payload) commit(ADD_ORDER, res.data) // 跨模塊通知各自處理各自的邏輯 await dispatch(cart/clearChecked, null, { root: true }) await dispatch(user/refreshPoints, null, { root: true }) return res.data }這樣order模塊不需要知道cart內部怎么實現(xiàn)只要知道有這么個 action 就行。耦合度低測試也好寫。如果模塊數量多、協(xié)作關系復雜可以再引入一個“編排層”專門寫跨模塊的 action把業(yè)務流程集中在一處。還有個小技巧跨模塊讀取數據用 getters不要直接讀rootState.xxx.yyy。getters 是一層抽象將來內部結構變了只要 getter 的返回不變調用方就不用改。5.3 表單草稿和列表緩存的取舍后臺系統(tǒng)里最常見的兩個需求表單填一半切走了回來要恢復列表翻到第五頁點進詳情再返回要停在第五頁。表單草稿我的做法是不進 store用sessionStorage加組件內的watch做防抖保存。原因很簡單草稿是頁面級的狀態(tài)多個表單同時編輯時放 store 會互相干擾還要處理各種清理邏輯。sessionStorage 天然按標簽頁隔離關掉就沒了符合直覺。列表緩存反而適合進 store。因為篩選條件、頁碼、排序方式這些是需要跨路由保留的而且詳情頁返回時要用。做法是在list模塊里存一份query對象列表頁onMounted時讀出來發(fā)起請求條件變化時同步更新。要注意的是從菜單重新點進列表時應該重置從詳情返回時應該保留這個區(qū)分靠路由的meta.keepAlive或者判斷from路徑來做。const actions { async loadList({ state, commit }, { reset false } {}) { if (reset) { commit(RESET_QUERY) } const res await api.getList(state.query) commit(SET_LIST, res.data) } }reset參數由調用方決定模塊本身不猜。這種“讓調用方明確表達意圖”的設計比在模塊里寫一堆 if 判斷當前路由要清晰得多。6. 我個人在實際項目里的幾點體會寫到這里Vuex 的主要知識點基本都覆蓋了。最后分享幾個不太適合寫進文檔、但實際干活時確實管用的經驗。第一別怕寫重復代碼。Vuex 的四段式state/getters/mutations/actions看起來很啰嗦但每多寫一行將來排查問題時就少猜一次。我曾經為了省事把 mutation 和 action 合并成一個函數結果 devtools 里全是匿名調用出問題時完全不知道是誰改的。后來老老實實拆開調試效率反而高了。第二給 store 加注釋比加文檔有用。每個模塊文件頂部寫清楚這個模塊管什么、依賴誰、被誰依賴比單獨維護一份文檔靠譜得多。文檔會過期代碼不會。我現(xiàn)在接手新項目第一件事就是看 store 模塊的頂部注釋五分鐘就能摸清業(yè)務脈絡。第三調試時善用 devtools 的 import/export。Vuex 面板可以把當前狀態(tài)導出成 JSON也能導入一份狀態(tài)來復現(xiàn)問題。遇到用戶反饋的詭異 bug讓對方導出一份狀態(tài)文件本地導入后就能完全復現(xiàn)當時的場景比反復溝通效率高太多。這個功能知道的人不多但真的好用。第四測試只測 action 和 getter。state 和 mutation 太簡單測了也是形式主義。真正有價值的是 action 里的業(yè)務流程和 getter 里的計算邏輯這兩塊寫單測覆蓋率能上一個大臺階。測 action 的時候記得 mock 掉commit和dispatch用jest.fn()或者vi.fn()都行斷言調用參數就夠了。最后提一句狀態(tài)管理這塊工具會換但“什么狀態(tài)該放在哪一層、變更走什么路徑、如何保證可追溯”這三個問題不會變。把 Vuex 這套東西吃透換成 Pinia、換成任何別的方案思路都是通用的。