當我們在開發前端專案時，常常會遇到明明在本地開發測試都好好的，但一打包部署到測試環境（ staging ），某些功能就莫名其妙失蹤的靈異事件！

這次苦主遇到的狀況是：使用 pnpm build:staging 指令打包後，左側導覽列的「管理員選單（ isAdmin ）」居然直接蒸發了！

經過一番鍵盤柯南式的徹查，終於抓到幕後黑手，原來是我們自以為很懂的 Vite 在搞鬼。

案發現場：為什麼選單不見了？

在原本的程式碼中，開發者用了 import.meta.env.PROD 來做判斷。心裡想著：「開發環境（ dev ）是 false ，測試環境（ staging ）應該也是 false ，只有真正的正式環境（ production ）才會是 true 吧？」

結果 Vite 表示：「你想得美！」

我們來看看 Vite 在不同指令下的真實真面目：

執行的指令	MODE 變數	PROD 變數（ 關鍵在這裡 ）	導致的後果
vite (dev)	development	false	順利繞過檢查，選單正常顯示。
vite build –mode staging	staging	true	誤判為正式環境，跑去呼叫真實 API 檢查，結果因為 IP 不對直接被拒絕，選單慘遭隱形。
vite build	production	true	正常的正式環境流程。

破案關鍵：在 Vite 的世界裡，只要你執行了 vite build 這個打包指令，不管後面帶的 –mode 是什麼，它都會偷偷把 NODE_ENV 設定為 production 。因此， import.meta.env.PROD 在測試環境下也會被無情地判定為 true ！

拯救選單：動手修正它

既然知道了 Vite 的脾氣，修正的方法就很簡單了。我們不要再相信傲嬌的 PROD 變數，直接去檢查 MODE 的名字是不是叫做 production 就好了！

程式碼改動

請把原本的防禦邏輯修改如下：

JavaScript

// ❌ 原本的寫法（ 會誤判測試環境 ）
if (!import.meta.env.PROD) { ... }

//  修正後的寫法（ 精準識別是不是真的正式環境 ）
if (import.meta.env.MODE !== 'production') { ... }

同時，別忘了同步更新專案的 README.md 說明文件，讓未來的自己或其他同事不會再踩進同一個坑裡。

修正後的快樂結局

改用 import.meta.env.MODE 來把關之後，判斷邏輯就變得非常聽話了：

• pnpm run dev 模式為 development 順利放行，直接顯示選單！
• pnpm run build:staging 模式為 staging 順利放行，直接顯示選單！
• pnpm run build 模式為 production 嚴格把關，呼叫 API 檢查！

現在重新執行 pnpm build:staging 打包，那個令人朝思暮想的管理員選單終於乖乖下凡，回歸到它該出現的地方囉！

        await queryClient.invalidateQueries({ queryKey: ['/api/suggestions/'], exact: false });
        // Use predicate because the key is a single string '/api/suggestions/{id}/logs'
        // and partial array prefix matching would not reach it.
        await queryClient.invalidateQueries({
            predicate: (query) =>
                typeof query.queryKey[0] === 'string' &&
                (query.queryKey[0] as string).endsWith('/logs'),
        });

    // The detail page may already be open (same SPA), so refetchOnWindowFocus won't fire.
    await queryClient.invalidateQueries({ queryKey: ['/api/suggestions/'], exact: false });
    await queryClient.invalidateQueries({
        predicate: (query) =>
            typeof query.queryKey[0] === 'string' &&
            (query.queryKey[0] as string).endsWith('/logs'),
    });

上面的紅色刪除 code, 綠色是新增的 code.

這段程式碼之所以能達成即時更新快取，關鍵在於它修正了 TanStack Query (React Query) 的快取清除機制，從原本失效的「前綴匹配」改為精準的「條件篩選」。

以下為您詳細拆解它的運作原理，以及快取內容是如何重新取得的：

1. 為什麼這樣子做，可以即時更新快取？

在原先的程式碼中，開發者試圖使用以下方式來讓快取失效：

TypeScript

// 舊寫法：無效
await queryClient.invalidateQueries({ queryKey: ['/api/suggestions/'], exact: false })

為什麼舊寫法會失敗？

React Query 在處理 queryKey 陣列時，預設的模糊匹配（exact: false）是比對陣列中的元素元素（Array Elements）。

如果你的 API 快取鍵值（Query Key）在設計時是一個單一字串（例如：'/api/suggestions/{id}/logs'），React Query 會認為這個陣列裡只有一個元素。它在比對時，會檢查 '/api/suggestions/{id}/logs' 是否「完全等於」或「為陣列前綴」，但它不會去把字串拆開做子字串匹配。因此，舊寫法完全找不到對應的快取，自然無法更新。

為什麼新寫法（Predicate）可以成功？

新程式碼改用 predicate 自訂篩選函式：

TypeScript

// 新寫法：成功
await queryClient.invalidateQueries({
  predicate: (query) =>
    typeof query.queryKey[0] === 'string' &&
    (query.queryKey[0] as string).endsWith('/logs'),
})

• 主動巡檢：predicate 就像是一個過濾器，它會遍歷目前瀏覽器記憶體中所有現存的 React Query 快取。
• 精準識別：不論 {id} 是多少（例如 /api/suggestions/123/logs 或 /api/suggestions/456/logs），只要快取鍵值的第 0 個元素是字串，且結尾是 '/logs'，就會被強制貼上「已過期（Stale）」的標籤。

透過這種方式，所有相關的審核紀錄快取（Suggestion Logs）就會在代理人變更的當下立刻失效，迫使畫面準備更新。

2. 快取內容又是如何去取得（重新發送請求）？

當 invalidateQueries 成功將這些快取標記為「已過期（Stale）」後，React Query 會根據當前頁面的狀態，自動透過以下邏輯去重新取得（Refetch）最新的資料：

狀況 A：該資料正顯示在當前畫面上（作用中的 Query）

如果使用者正停留在該審核紀錄的頁面上（該 Query 處於 active 狀態），一旦 invalidateQueries 被執行，React Query 會立刻在背景自動觸發對應的 API 請求（例如呼叫後端後台 GET /api/suggestions/{id}/logs），取得最新含有新代理人資訊（approvalProgress.reviewer_delegate_id）的資料，並在收到回應後即時渲染、更新畫面。

狀況 B：該資料目前沒顯示在畫面上（非作用中的快取）

如果使用者目前在其他分頁，這些被標記為過期的快取會先靜靜地待在記憶體中。直到使用者切換回該詳細頁面、畫面重新掛載（Mount）該元件時，React Query 偵測到「快取已過期」，就會在初始化時立刻發送 API 請求撈取最新資料，確保使用者看到的絕對不會是舊代理人的髒資料（Dirty Data）。

什麼是 SPA？

傳統的網站（Multi-Page Application, MPA）在你點擊連結、切換頁面時，瀏覽器會向伺服器重新請求一個全新的 HTML 檔案，畫面會整個閃一下、重新載入。

而 React 打造的 SPA 正好相反：

• 只有一個 HTML 檔案： 瀏覽器只在第一次進入網站時，下載一個基本上是空白的 index.html 和一大包 JavaScript（React 程式碼）。
• 前端路由（Client-side Routing）： 當你在網站內切換頁面（例如從首頁到設定頁）時，瀏覽器並不會向伺服器重新請求新網頁。React Router 等套件會攔截點擊事件，直接在前端用 JavaScript 把舊的組件（Component）拔掉，換上新的組件。
• 體驗流暢： 因為不需要重新整理網頁，頁面切換就像桌面軟體或 App 一樣秒開、極度流暢。

解讀你遇到的問題

你提到的這句話非常精準地點出了 SPA 的特性：

“The refetchOnWindowFocus doesn’t fire when navigating within the same SPA.”

如果你使用的是 TanStack Query (React Query) 或類似的 Data Fetching 套件，refetchOnWindowFocus 的觸發條件是「瀏覽器視窗重新獲得焦點」（例如：你切換到別的視窗看 LINE，再切回瀏覽器；或者切換分頁再切回來）。

因為在同一個 SPA 裡面切換頁面（Navigating）：

1. 視窗從頭到尾都沒有失去焦點，瀏覽器只是在執行 React 的組件切換。
2. 對瀏覽器來說，使用者根本沒有「離開視窗再回來」。
3. 因此，refetchOnWindowFocus 絕對不會因為你在 SPA 內轉址而觸發。

你的解決方案完全正確

“The real fix is: invalidate getMe and all suggestion logs from AccessRolesPage after removing the reviewer delegate”

這正是處理 SPA 狀態同步的標準標準做法（Best Practice）：

在 SPA 中，因為頁面不會重新載入，舊頁面的快取數據可能還留在記憶體中。當你執行了某個動作（例如：移除審查員代理人 reviewer delegate），後端的資料已經變了，但前端畫面可能還看得到舊資料。

透過主動呼叫 queryClient.invalidateQueries：

• 你明確告訴 React Query：「getMe 和 suggestion logs 這幾筆資料已經過期（stale）了！」
• React Query 就會立刻在背景重新向 API 發送請求（Refetch），確保使用者切換到 AccessRolesPage 時，看到的是最新的正確資料。

這種「動作完成後，主動使相關快取失效」的機制，是維持 SPA 資料同步最乾淨、最不通靈的解法！

要理解它為什麼能提升效率，我們需要先來看看 React 的運作機制。

為什麼需要 useMemo？

在網頁運作時，只要元件的狀態（State）或屬性（Props）發生改變，React 就會重新渲染該元件。重新渲染意味著元件內部的所有程式碼，都會從上到下重新執行一次。

想像一下，如果你的元件內有一個需要處理上萬條資料的排序函式，每次畫面一有風吹草動，這個排序函式就要重新跑一次，這會消耗極大的瀏覽器運算資源，導致畫面出現卡頓。

useMemo 就是為了解決這個問題而誕生的。

useMemo 的運作原理

useMemo 的基本語法如下：

JavaScript

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

它接收兩個參數：

1. 一個帶有回傳值的函式，裡面放置你需要進行的複雜運算。
2. 一個陣列，稱為「相依陣列」（Dependency Array）。

它的工作流程非常聰明：

1. 記憶結果

當元件第一次渲染時，useMemo 會執行內部的函式，並把算好的結果存到記憶體中。

2. 比對相依陣列

當元件重新渲染時，useMemo 會去檢查相依陣列裡面的變數（例如上面的 a 和 b）有沒有發生改變。

3. 決定是否重新計算

• 如果 a 和 b 的值跟上一次一模一樣，useMemo 就會直接從記憶體拿取上一次算好的結果，完全跳過內部的運算函式。
• 只有當 a 或 b 的值改變了，它才會重新執行運算，並更新記憶體裡的暫存答案。

為什麼這樣可以提升效率？

我們用一個生活中的例子來比喻：

假設老師每天都會考你一題非常複雜的數學題。

• 沒有使用 useMemo 的情況：你每天早上拿到題目，就算題目跟昨天完全一樣，你還是老老實實地在計算紙上從第一步算到最後一步，花了 20 分鐘才寫出答案。
• 使用了 useMemo 的情況：你發現題目沒變，於是直接翻開昨天的筆記本，把寫在上面的答案抄上去，只花了 2 秒鐘。只有當老師換了新題目，你才會重新動筆計算。

在程式裡也是一樣。透過快取機制，useMemo 幫瀏覽器省去了大量重複的 CPU 計算時間，讓網頁反應變得更加流暢。

什麼時候該用 useMemo？

雖然 useMemo 很好用，但這並不代表所有地方都應該加上它。因為「把資料存進記憶體」以及「每次比對相依陣列」本身也需要消耗微小的效能。

以下是適合使用的情境：

1. 處理大量資料的運算：例如高達數千筆資料的過濾（Filter）、排序（Sort）或複雜轉換。
2. 避免不必要的子元件渲染：當你把一個物件或陣列當作 Props 傳給子元件時，因為 JavaScript 每次重新渲染都會產生新的物件記憶體位址，會導致子元件誤以為資料變了而跟著重新渲染。這時候用 useMemo 把物件固定住，就能阻止子元件浪費效能。

如果只是簡單的加減乘除或少數資料的處理，直接讓 React 重新計算即可，不需要刻意使用 useMemo。