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外部依赖
| 类型 | 依赖 |
|---|---|
| package | @gsap/react（useGSAP hook 包） |
| package | gsap（动画引擎本体） |
| network | GSAP 官方 React 资源页 |
4风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- 依赖 @gsap/react 版本行为 — useGSAP 的清理与 revertOnUpdate 语义随 @gsap/react 版本演进；skill 未固定版本号（示例工程里是 ^2.1.2），跨版本使用需核对。
- 清理纪律仍靠模型执行 — scope/contextSafe/ctx.revert() 都是提示约束；漏写不会报错但会在开发模式下出现 React 警告与内存增长，需 code review 兜底。
- SSR 违规只在服务端暴露 — 在 Next.js 等环境误在渲染期调用 gsap/ScrollTrigger 会报错或产出水合不一致，本地纯客户端开发时不易发现。
- 版本漂移 — React 18/19 与 Next.js 各版本的 effect 语义差异可能影响 useGSAP 内部选择；本分析只对 pin aed9cfd 有效。
风险提醒：绿色，放心使用。纯指令型 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 / Next.js 里用 GSAP 的项目，尤其是 SPA 路由切换、组件卸载频繁、或已在受内存泄漏困扰的代码库；也适合作为团队「React 动画规范」的评审清单。
不适合：不适合 Vue/Svelte 项目（用 gsap-frameworks）；不适合只用 CSS 动画或无动画需求的项目；不适合期望 skill 提供 React 之外的 GSAP API 教学的场景（那些在 gsap-core / gsap-timeline / gsap-scrolltrigger）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 gsap-react.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent63017b31e6b9c157…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库greensock / greensock/gsap-skills
原始 GitHubgreensock/gsap-skills ↗
Stars15326
最近推送2026-07-29
本 skill commit
aed9cfd327许可MIT（仓库根 LICENSE，Copyright (c) 2026 GreenSock；GitHub API spdx_id=MIT；每个 SKILL.md frontmatter 亦写 license: MIT）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。