优化Web动画
核心规则
在编辑前先测量真实页面。目标不是移除动效,而是让离屏工作停止,可见动效正确恢复,并且路由/卸载清理释放长期占用的资源。
尽可能使用Codex Browser,特别是对于localhost页面。除非用户明确要求,否则不要使用Chrome。
工作流程
-
检查仓库上下文。
- 阅读
AGENTS.md或本地说明。 - 尽早运行
git status --short。 - 查找页面组件、动画钩子、CSS关键帧、
requestAnimationFrame、setInterval、setTimeout、Canvas/WebGL/物理引擎组件、媒体元素、GSAP时间线/补间动画以及现有的可见性工具。 - 检查副作用清理中是否包含事件监听器、观察器、RAF循环、间隔、定时器、外部脚本、媒体流、WebGL纹理/材质/几何体/渲染器,以及可能在卸载后完成的异步工作。
- 如果工作树不干净,一开始就计划好狭窄的暂存范围。
- 阅读
-
在浏览器中采集基线。
- 打开用户指定的确切路由。
- 在页面顶部、中部、页脚/底部内容以及一个移动端视口(布局可能不同时)进行性能分析。
- 通过计算得到的
animationName、animationPlayState和可见性来统计CSS动画数量。包括::before和::after。 - 单独检查Canvas/WebGL元素;CSS性能分析不能证明RAF循环已停止。
- 记录哪些动画在屏幕外运行以及负责的DOM所有者。
- 对于内存/泄漏相关询问,还要记录元素/Canvas/图像/iframe计数、可用的暴露JS堆指标、10-30秒后的空闲采样,以及一次短的路由循环采样。如果堆API返回
null或浏览器沙箱阻止了猴子补丁,请说明情况,并依赖稳定的可观察计数和源代码审查。 - 保持压力测试在可控范围内。浏览器标签页在性能分析过程中崩溃是过载的证据,但除非通过最小测试复现,否则不要过度归因。
- 参见
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渲染循环。 - 对于泄漏加固:
- 清除由该效果创建的每一个超时/间隔。
- 在卸载前和重启循环前取消RAF。
- 断开
IntersectionObserver、ResizeObserver、MutationObserver和自定义订阅。 - 使用相同的处理程序引用移除全局/窗口/文档监听器。
- 销毁Three/WebGL纹理、材质、几何体、渲染器,并移除渲染器DOM节点。
- 终止DOM节点和可变对象(如着色器uniform)的GSAP补间/时间线。
- 停止媒体流并暂停分离的视频/音频源。
- 用
isDisposed标志保护异步加载器,并在卸载后解析时销毁已加载的资源。 - 在React清理中,如果lint警告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
# 仅将意图的hunk应用到临时索引。
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
- 除非每个hunk都属于当前任务,否则永远不要从脏工作树暂存宽泛的文件。
- 提供有证据的报告。
- 以发现结果开头:哪些仍在运行,哪些看起来容易泄漏,以及哪些无法测量。
- 将源代码审查风险与实时浏览器测量分开。
- 包括确切采样的路由、屏幕外动画计数、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 refs的捕获清理节点。
- 用于可能在卸载后解析的图像/视频/纹理/数据加载器的
isDisposed守卫。 - 短时间空闲和路由循环探测,用于捕获累积的DOM节点、Canvas、iframe或未释放的媒体。
避免
- 移除所有动画以使性能分析通过。
- 因为祖先选择器范围太宽而暂停可见的Hero动效。
- 假设
animation-play-state能覆盖伪元素或JavaScript RAF循环。 - 在长页面上仅信赖单个页面顶部的测量值。
- 将不可用的堆计数器视为没有内存泄漏的证据。
- 在浏览器中运行无限制的压力循环;使用有界的循环并在不过度推断因果关系的情况下记录崩溃。
- 仅使用截图作为性能证明。
- 让不相关的本地hunk混入提交中。