最佳化網頁動畫
核心規則
在編輯之前先測量真實頁面。目標不是移除動畫,而是讓離螢幕的工作停止,可見的動畫正確恢復,並且路由/卸載清理能釋放長期存在的資源。
盡可能使用 Codex Browser,尤其是對於 localhost 頁面。除非使用者明確要求,否則不要使用 Chrome。
工作流程
-
檢查儲存庫上下文。
- 讀取
AGENTS.md或本地說明。 - 提早執行
git status --short。 - 尋找頁面元件、動畫鉤子、CSS keyframes、
requestAnimationFrame、setInterval、setTimeout、canvas/WebGL/物理引擎元件、媒體元素、GSAP 時間軸/補間、以及現有的可見性工具函式。 - 搜尋 useEffect 清理中是否有事件監聽器、觀察器、RAF 迴圈、間隔、計時器、外部腳本、媒體串流、WebGL 紋理/材質/幾何/渲染器,以及在卸載後才完成執行的非同步工作。
- 如果工作目錄是髒的,從一開始就規劃狹隘的暫存。
- 讀取
-
在瀏覽器中擷取基準資料。
- 開啟使用者指定的確切路由。
- 在頁面頂部、中間、頁尾/底部內容處進行設定檔分析,並在版面可能不同時對一個行動視埠進行分析。
- 透過計算出的
animationName、animationPlayState和可見性來計算 CSS 動畫數量。包含::before和::after。 - 分別檢查 canvas/WebGL 元素;CSS 設定檔分析無法證明 RAF 迴圈已停止。
- 記錄哪些動畫名稱在離螢幕時仍在執行,以及負責的 DOM 擁有者。
- 對於記憶體/洩漏相關請求,也要記錄元素/canvas/影像/iframe 的數量、可用的公開 JS 堆積指標、10-30 秒後的閒置取樣,以及一個簡短的路由循環取樣。如果堆積 API 回傳
null或瀏覽器沙箱阻止了 monkey-patching,請說明情況並依賴穩定的可觀察計數加上原始碼稽核。 - 保持壓力測試在有限範圍內。瀏覽器分頁在設定檔分析期間崩潰是負載過重的證據,但除非能透過最小化測試重現,否則不要過度歸因其成因。
- 請參閱
references/browser-profiling.md以獲得可重複使用的 Codex Browser 評估器。
-
修補控制動畫的最小擁有者。
- 如果應用程式已有現成的頁面顯現/可見性鉤子,優先使用。
- 否則,新增一個
IntersectionObserver,在章節和動畫子元素上切換一個穩定的類別,例如is-offscreen。 - 使用目標規則暫停 CSS 動畫:
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- 對於重複的卡片或佔位符,觀察卡片外殼和動畫子代,而不是整個文件。
- 對於跑馬燈/股票行情軌道,在其章節離螢幕時暫停軌道。
- 對於骨架載入器和偽元素微光,在需要時包含
::before和::after暫停選擇器。 - 對於 canvas/WebGL/物理引擎迴圈,直接閘控 RAF 迴圈:
- 當 canvas/容器進入可視區域時啟動。
- 當離螢幕時取消
requestAnimationFrame。 - 重新進入時恢復。
- 在清理時中斷觀察器並取消幀。
- 在需要協助瀏覽器驗證時,新增一個非視覺的除錯標記,例如
data-animation-active。
- 如果元件已經這麼做,請尊重
prefers-reduced-motion,並避免為捲動/動畫狀態引入 React 渲染迴圈。 - 針對記憶體洩漏防護:
- 清除由該 useEffect 建立的每個 timeout/interval。
- 在卸載前和重新啟動迴圈前取消 RAF。
- 中斷
IntersectionObserver、ResizeObserver、MutationObserver和自訂訂閱。 - 使用相同的處理器參考移除全域/視窗/文件監聽器。
- 釋放 Three/WebGL 的紋理、材質、幾何、渲染器,並移除渲染器 DOM 節點。
- 銷毀 DOM 節點和可變物件(如著色器 uniform)的 GSAP 補間/時間軸。
- 停止媒體串流並暫停已分離的影片/音訊來源。
- 使用
isDisposed標誌保護非同步載入器,並在載入於卸載後完成時釋放已載入的資源。 - 在 React 的清理函式中,如果在 useEffect 回傳清理函式之前,linter 警告 ref 可能改變,請在 effect 內部捕獲
ref.current的值。 - 在可見性暫停後限制物理引擎或模擬的幀增量,以便延遲的幀不會執行過大的更新。
-
驗證行為,而不僅僅是建置。
- 重新載入路由並重新執行相同的頂部/中間/頁尾/行動設定檔分析。
- 目標結果:受測頁面章節的
offscreenRunningCount: 0。 - 確認可見的動畫在捲動進入可視區域時仍然執行或恢復。
- 確認 RAF/canvas 迴圈在離螢幕時報告為非活躍,在可視區域內時為活躍,或者從原始碼/執行時期狀態證明其已取消。
- 對於記憶體洩漏稽核,比較前後的路由循環和閒置取樣。DOM/canvas/影像計數在重複導航後應回到相同的基準線,允許少量預期的非同步內容變更。
- 執行一次正常的頁面互動,例如搜尋/篩選/導航,以便觀察器不會破壞動態內容。
- 檢查新分頁的主控台警告/錯誤。
-
執行本地檢查。
- 使用儲存庫的正常閘道。對於 React/Vite 應用程式,這通常是:
git diff --check
npm run lint
npm run build
- 將已知的非致命警告與失敗分開說明。
- 根據儲存庫/使用者指示的要求,進行狹隘的提交。
- 如果存在不相關的髒變更,請使用隔離的索引:
rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# 僅將預期的區塊套用到暫存索引。
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "暫停離螢幕 <page> 動畫"
git restore --staged <files> 2>/dev/null || true
- 除非每個區塊都屬於該任務,否則永遠不要從髒的工作目錄中暫存廣泛的檔案。
- 附帶證據進行報告。
- 以發現結果為開頭:哪些仍然在執行,哪些看起來有洩漏風險,以及哪些無法測量。
- 分別說明原始碼稽核的風險和即時瀏覽器測量結果。
- 包含確切的取樣路由、離螢幕動畫計數、DOM/canvas 計數穩定性、路由循環結果和本地檢查。
- 清楚地說明限制,特別是無法使用的堆積計數器或被阻斷的瀏覽器檢測工具。
良好的修復模式
- 章節層級的
is-offscreen加上元素層級的is-offscreen,用於較長的章節,其中折疊下方子動畫仍可能執行。 - 每個路由的共用可見性選擇器常數,例如
COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR。 IntersectionObserver閾值約為0.01以進行動畫閘控。- 對於 WebGL/canvas 效果,直接控管 RAF 迴圈;CSS
animation-play-state無法暫停 JavaScript 渲染迴圈。 - 針對在暫停或延遲幀後恢復的物理引擎迴圈的幀增量上限。
- 為 GSAP/WebGL 效果使用的 React ref 所捕獲的清理節點。
- 用於可能在卸載後才解析的影像/影片/紋理/資料載入器的
isDisposed保護。 - 簡短的閒置和路由循環探測,以捕捉累積的 DOM 節點、canvas、iframe 或未釋放的媒體。
應避免的事項
- 為了通過設定檔分析而移除所有動畫。
- 因為祖先選擇器太過寬泛而暫停可見的主要動畫。
- 假設
animation-play-state涵蓋了偽元素或 JavaScript RAF 迴圈。 - 在長頁面上只相信單一頁頂測量值。
- 將無法使用的堆積計數器視為沒有記憶體洩漏的證據。
- 在瀏覽器中執行無限制的壓力迴圈;使用有限循環並記錄崩潰,但不要過度歸因因果關係。
- 僅使用螢幕截圖作為效能證明。
- 讓不相關的本地區塊混入提交中。