1实现原理 · 为什么它能做到

给出 React 的唯一首选方案：@gsap/react 的 useGSAP()，并由它替代 useEffect 承担清理职责。

skills/gsap-react/SKILL.md

It handles cleanup automatically and provides a scope and **contextSafe** for callbacks.

为什么能实现宣称功能：useGSAP = useLayoutEffect/useEffect + gsap.context 的封装，卸载时自动 revert 该上下文创建的所有动画与 ScrollTrigger；skill 把「React 泄漏」这个常见问题在框架层一次性消掉。

注册纪律：useGSAP 本身是插件，必须先 registerPlugin 再使用（与 gsap-plugins 的同一约定互为印证）。

skills/gsap-react/SKILL.md

gsap.registerPlugin(useGSAP); // register before running useGSAP or any GSAP code

漏注册会导致 hook 行为不完整（contextSafe/清理不生效），且不会抛错——典型的静默失败，故写在示例第一行。

scope 是强制项而非可选优化：选择器必须被限定在组件根节点内，Do Not 明确禁止「无 scope 的选择器」。

skills/gsap-react/SKILL.md

❌ Target by **selector without a scope**; always pass **scope** (ref or element) in useGSAP or gsap.context() so selectors like `.box` are limited to that root and do not match elements outside the component.

这里在做什么：把「组件里用全局选择器会误伤页面其它元素」这条 React 特有陷阱变成硬规则；同时给出第二参数既可为依赖数组也可为配置对象的两种形态。

contextSafe 处理「运行时才创建的动画」：事件回调里 new 出来的 tween 不在上下文内，卸载后不会被回收。

skills/gsap-react/SKILL.md

This animation is created in an event handler that executes AFTER useGSAP() executes.

skill 用 badRef/goodRef 对照代码同时演示两种失败：动画未入上下文 + 事件监听未移除；正解是 contextSafe 包裹回调并在 cleanup 里 removeEventListener。这段是「为什么需要 contextSafe」的最佳解释。

非 useGSAP 场景给出等价兜底：useEffect + gsap.context() + ctx.revert()，并要求「永远」返回清理。

skills/gsap-react/SKILL.md

return () => ctx.revert();

说明适用条件：@gsap/react 不可用、或确实需要 effect 自身的依赖/触发行为时；只要用 useEffect 就必须配 ctx.revert()，否则内联样式与实例会残留在已卸载节点上。

SSR 边界：GSAP 是浏览器库，禁止在服务端渲染阶段调用 gsap/ScrollTrigger。

skills/gsap-react/SKILL.md

GSAP runs in the browser. Do not call gsap or ScrollTrigger during SSR.

Next.js 等场景的可行解：动画全部放进 useGSAP/useEffect（天然只在客户端跑），或按需在 effect 内动态 import 以控制包体。

2核心能力

01useGSAP 优先的动画装配（自动清理 + 作用域 + 配置对象）

02scope 沙箱：选择器仅命中组件内部（ref 或元素）

03contextSafe：把事件回调里创建的动画纳入上下文，保证卸载可回收

04gsap.context() + ctx.revert() 手工清理路径（useEffect 场景）

05dependencies / revertOnUpdate 控制重跑与重拆

06refs 作为目标（避免跨渲染匹配到错误元素）与多元素容器查询

07SSR 安全：动画只在客户端生命周期内运行

3外部依赖

Kind	Dependency / Endpoint
package	@gsap/react（useGSAP hook 包）
package	gsap（动画引擎本体）
network	GSAP 官方 React 资源页

4管控建议与判定依据

建议配套管控措施

面向 Agent

可自动加载

面向管理者

登记来源与版本

判定依据（文件路径与关键语句摘要）

SKILL.md: 纯提示词指令与规则文本，无脚本执行与外部影响

审计说明： 。纯指令型 skill：目录内仅 SKILL.md（6,565 B），无脚本、无网络外发、无凭证读取、无文件写入；外链一条（gsap.com/resources/React）。它引入的两个 npm 依赖（gsap、@gsap/react）是安装指令而非 skill 自行安装——供应链风险取决于使用者自己执行 npm install 时的来源，skill 未涉及凭证或私有 registry。注意点：清理纪律（scope/contextSafe/revert）是提示层约束，漏做会造成内存泄漏与陈旧节点更新，属正确性而非安全风险。

5第二遍独立确认

[ok] 目录资产面：仅 SKILL.md — skills/gsap-react/ 下唯一文件 SKILL.md（6,565 B）；无 scripts/、references/、示例工程（示例在仓库 examples/react/）。
[ok] external_deps 逐条核实 — 两条 npm install 指令（gsap、@gsap/react）与一条 gsap.com/resources/React 链接均在文件内逐字命中。
[ok] useGSAP 行为描述是否与官方 hook 一致 — 「handles cleanup automatically」「provides a scope and contextSafe」与 @gsap/react 的 useGSAP 官方文档一致；dependencies/revertOnUpdate 配置项名称真实。
[ok] contextSafe 段落是否是真实失败模式（非编造） — 原文给出可复现机制：事件回调在 useGSAP 执行之后创建 tween → 不入上下文 → 卸载不回收；并指出监听器未移除会跨渲染残留。逻辑自洽且符合 gsap.context 的设计。
[ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；URL 仅 1 条官方资源页。
[ok] 与 gsap-frameworks 分工是否重复 — gsap-react 首段声明 React 用本 skill、Vue/Svelte 用 gsap-frameworks；gsap-frameworks 亦反向声明「For React specifically, use gsap-react」，无内容重叠冲突。
[ok] 元数据与 pin — frontmatter license: MIT；HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z。
[ok] examples/react 与本文一致性 — examples/react/App.jsx 用 useGSAP + { scope: containerRef } + 注册 useGSAP，与 skill 的 Do/Do-Not 完全对应。

6结论

给出 React 侧唯一主路径（useGSAP）并解释其为何能自动清理，避免团队在 useEffect 手写清理上反复踩坑。

正反例对照把 contextSafe 的必要性讲透：事件回调中创建的动画不入上下文、监听不移除会跨渲染残留。

scope 作为硬规则写进 Do Not，直接对治「组件动画误伤全页元素」的高频 bug。

覆盖 SSR 边界（Next.js），并给出「动画只在客户端跑/按需动态 import」两种解法。

薄而准：6.5 KB 只讲接缝，GSAP 语法交给 core/timeline/scrolltrigger，学习与加载成本都低。

适合： 适合所有在 React / Next.js 里用 GSAP 的项目，尤其是 SPA 路由切换、组件卸载频繁、或已在受内存泄漏困扰的代码库；也适合作为团队「React 动画规范」的评审清单。

不适合： 不适合 Vue/Svelte 项目（用 gsap-frameworks）；不适合只用 CSS 动画或无动画需求的项目；不适合期望 skill 提供 React 之外的 GSAP API 教学的场景（那些在 gsap-core / gsap-timeline / gsap-scrolltrigger）。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload gsap-react.tar.gz

sha256: 63017b31e6b9c157…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit aed9cfd327.