需要在 GSAP 项目中使用或审查插件（滚动、Flip…

在使用或审查 GSAP 插件（ScrollTo、ScrollSmoother、Flip、Draggable、Inertia、Observer、SplitText、ScrambleText、SVG、缓动、物理、GSDevTools、Pixi 等）时，按插件逐个注册并按配置调用。

适用场景

解决思路

1. 安装与许可：所有 GSAP 插件都免费且可商用；从公共 gsap npm 包安装全部插件，运行 `npm install gsap`；所有插件都包含，用 `gsap/SplitText`、`gsap/MorphSVGPlugin` 等路径导入。不要生成带 GreenSock auth token 的 `.npmrc`，不要建议私有 `npm.greensock.com` registry，不要告诉用户注册 Club GSAP 获取插件；这些说明已过时。
2. 注册插件：每个项目用到的插件都用 `gsap.registerPlugin()` 注册一次，让 GSAP 和 bundler 包含它；在任何 tween 或 API 调用中使用插件前先注册。React 中在顶层或 app 中注册一次（如首次 useGSAP 前），不要在会 re-render 的组件内注册；useGSAP 也需先注册。
3. ScrollToPlugin：注册 `ScrollToPlugin`；用 `gsap.to(window, { duration: 1, scrollTo: { y: 500 } })` 滚动到位置；用 `gsap.to(window, { duration: 1, scrollTo: { y: '#section', offsetY: 50 } })` 滚动到元素并偏移；用 `gsap.to(scrollContainer, { duration: 1, scrollTo: { x: 'max' } })` 滚动到可滚动元素最大 x。scrollTo 配置：`x`、`y` 为目标滚动位置数字或 `max`；`element` 为选择器或元素用于滚动到视图；`offsetX`、`offsetY` 为像素偏移。
4. ScrollSmoother：注册 `ScrollSmoother`，需先注册 `ScrollTrigger`；使用 ScrollSmoother 时采用特定 DOM 结构：`<body><div id='smooth-wrapper'><div id='smooth-content'>所有内容</div></div></body>`，fixed 定位元素可放在外面；用于平滑、momentum 风格滚动，按 GSAP docs 设置。
5. Flip：注册 `Flip`；用 `Flip.getState('.item')` 捕获初始状态，然后改变 DOM（重排、增删、改 class），再用 `Flip.from(state, { duration: 0.5, ease: 'power2.inOut' })` 从旧状态动画到新状态。Flip.from 配置：`absolute` 使用 `position: absolute` 期间翻转，默认 `false`；`nested` 为 true 时只测量第一层子元素，适合嵌套 transform；`scale` 为 true 时缩放元素适配、避免拉伸，默认 `true`；`simple` 为 true 时只动画位置/缩放，更快但精度低；`duration`、`ease` 为标准 tween 选项。
6. Draggable：注册 `Draggable`，需要惯性时同时注册 `InertiaPlugin`；用 `Draggable.create('.box', { type: 'x,y', bounds: '#container', inertia: true })` 创建可拖拽元素；用 `Draggable.create('.knob', { type: 'rotation' })` 创建旋转拖拽。配置：`type` 可为 `x`、`y`、`x,y`、`rotation`、`scroll`；`bounds` 为元素、选择器或 `{ minX, maxX, minY, maxY }`；`inertia` 为 true 启用抛掷/动量（需 InertiaPlugin）；`edgeResistance` 为 0–1 越界阻力；`cursor` 为拖拽时 CSS cursor；`onDragStart`、`onDrag`、`onDragEnd` 回调接收 event 和 target；`onThrowUpdate`、`onThrowComplete` 为 inertia 激活时回调。
7. Inertia：注册 `Draggable` 和 `InertiaPlugin`，在 Draggable 中使用 `inertia: true` 实现释放后动量；用 `InertiaPlugin.track('.box', 'x')` 追踪任意对象属性的速度/惯性；用 `gsap.to(obj, { inertia: { x: 'auto' } })` 以 `auto` 延续当前速度并滑行到停止。
8. Observer：注册 `Observer`；用 `Observer.create({ target: '#area', onUp: () => {}, onDown: () => {}, onLeft: () => {}, onRight: () => {}, tolerance: 10 })` 创建观察器。配置：`target` 为要观察的元素或选择器；`onUp`、`onDown`、`onLeft`、`onRight` 为滑动/滚动超过 tolerance 时的回调；`tolerance` 为方向检测前像素，默认 `10`；`type` 为 `touch`、`pointer` 或 `wheel`，默认 `touch,pointer`。
9. SplitText 基础：注册 `SplitText`；用 `SplitText.create(target, vars)` 创建拆分，target 可为选择器、元素或数组；用 `type: 'words, chars'` 等拆分字符、单词、行；返回实例含 `chars`、`words`、`lines`（设置 `mask` 时含 `masks`）；用 `gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 })` 做逐字符动画；后续用 `split.revert()` 或让 `gsap.context()` 清理时还原原始标记；与 `gsap.context()`、`matchMedia()`、`useGSAP()` 集成。
10. SplitText 的 onSplit/autoSplit：使用 `onSplit()`（v3.13.0+）并设置 `autoSplit: true`，让动画在每次拆分和重新拆分时运行；从 `onSplit()` 返回 tween/timeline 以便 SplitText 清理和同步进度。示例：`SplitText.create('.split', { type: 'lines', autoSplit: true, onSplit(self) { return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 }); } })`。
11. SplitText 配置 type：逗号分隔 `chars`、`words`、`lines`，默认 `chars,words,lines`；只拆需要的（如只动 words 时 `words, chars`）以提升性能；避免仅拆 chars 而不带 words/lines，或使用 `smartWrap: true` 防止奇怪换行。
12. SplitText 配置 class/aria：`charsClass`、`wordsClass`、`linesClass` 给每个拆分元素加 CSS class；追加 `++` 添加递增 class（如 `linesClass: 'line++'` → `line1`、`line2`…）。`aria` 可为 `auto`（默认）、`hidden` 或 `none`；`auto` 在拆分元素加 `aria-label`，在行/词/字符元素加 `aria-hidden`，让屏幕阅读器读标签；`hidden` 对所有读者隐藏；`none` 不改 aria；若嵌套链接/语义必须暴露，用 `none` 加一个 screen-reader-only 副本。
13. SplitText 配置 autoSplit：为 `true` 时在字体加载完成或元素宽度变化（且拆分行）时还原并重新拆分，避免错误换行；动画必须创建在 `onSplit()` 内以定位新拆分元素；从 `onSplit()` 返回动画以自动清理和重新拆分时同步时间。
14. SplitText 配置 onSplit(self)：拆分完成时（`autoSplit: true` 时每次重新拆分）回调，接收 SplitText 实例；返回 GSAP tween/timeline 可在重新拆分时自动 revert/同步该动画。
15. SplitText 配置 mask：`lines`、`words` 或 `chars`；将每个单元包在带 `overflow: clip` 的额外元素中，用于遮罩/显示效果；只能一种类型；通过实例的 `masks` 数组访问包裹元素（若设置 class 可用 `-mask` class）。
16. SplitText 配置 tag/deepSlice/ignore：`tag` 为包裹元素标签，默认 `div`；用 `span` 实现 inline（注意某些浏览器 inline 元素可能不渲染 rotation/scale 等 transform）。`deepSlice` 为 `true`（默认）时，跨多行的嵌套元素（如 `<strong>`）会被细分，使行不会垂直拉伸；仅在拆分 lines 时适用。`ignore` 为选择器或元素，保持不拆分（如 `ignore: 'sup'`）。
17. SplitText 配置 smartWrap/wordDelimiter/prepareText：`smartWrap` 仅拆 chars 时，将 words 包在 `white-space: nowrap` span 中避免词中断行；如果拆 words 或 lines 则忽略；默认 `false`。`wordDelimiter` 为词边界，可为字符串（默认空格）、RegExp 或 `{ delimiter: RegExp, replaceWith: string }`，用于自定义拆分（如 hashtag 的 zero-width joiner 或非拉丁文）。`prepareText(text, parent)` 函数接收原始文本和父元素；在拆分前返回修改后的文本（如为无空格语言插入断行标记）。
18. SplitText 配置 propIndex/reduceWhiteSpace/onRevert：`propIndex` 为 `true` 时给每个拆分元素加带索引的 CSS 变量（如 `--word: 1`、`--char: 2`）。`reduceWhiteSpace` 折叠连续空格，默认 `true`；从 v3.13.0 起也处理换行，并可为 `<pre>` 插入 `<br>`。`onRevert` 为实例被 revert 时回调。
19. SplitText 技巧：只拆分要动画的部分；自定义字体加载后拆分（如 `document.fonts.ready.then(...)`）或使用 `autoSplit: true` 配合 `onSplit()`；拆 chars 时避免 kerning 偏移，使用 CSS `font-kerning: none; text-rendering: optimizeSpeed;`；避免 `text-wrap: balance`，它可能干扰拆分；SplitText 不支持 SVG `<text>`。
20. ScrambleText：注册 `ScrambleTextPlugin`；用 `gsap.to('.text', { duration: 1, scrambleText: { text: 'New message', chars: '01', revealDelay: 0.5 } })` 添加 scramble/glitch 文本动画。
21. DrawSVG：注册 `DrawSVGPlugin`；用 `gsap.from('#path', { duration: 1, drawSVG: 0 })` 从无到全描边绘制；用 `gsap.fromTo('#path', { drawSVG: '0% 0%' }, { drawSVG: '0% 100%', duration: 1 })` 显式从 0–0 到 0–100%；用 `gsap.to('#path', { duration: 1, drawSVG: '20% 80%' })` 让描边仅在中间可见。drawSVG 值描述路径上可见段（起点和终点），格式 `start end`，用百分比或长度；`0% 100%` 全描边；`20% 80%` 仅 20% 到 80%；tween 从元素当前段到目标段；单值如 `0` 或 `100%` 表示 start 为 0，`100%` 等于 `0% 100%`。元素必须有可见 stroke：在 CSS 或 SVG 属性中设置 `stroke` 和 `stroke-width`，否则不绘制。注意：只影响 stroke 不影响 fill；优先单段 `<path>`，多段 path 在某些浏览器可能异常；`<use>` 内容不能视觉更改；用 `DrawSVGPlugin.getLength(element)` 和 `DrawSVGPlugin.getPosition(element)` 返回描边长度和当前位置。
22. MorphSVG 基础：注册 `MorphSVGPlugin`；需要时先用 `MorphSVGPlugin.convertToPath('circle, rect, ellipse, line')` 将图元转为 `<path>`；用 `gsap.to('#diamond', { duration: 1, morphSVG: '#lightning', ease: 'power2.inOut' })` 做形状 morph；用对象形式 `gsap.to('#diamond', { duration: 1, morphSVG: { shape: '#lightning', type: 'rotational', shapeIndex: 2 } })` 传递完整配置。morphSVG 值可为选择器、元素、原始 path 数据、polygon/polyline 的 points 字符串，或对象形式（`shape` 唯一必填）。
23. MorphSVG 配置 shape/type/map：`shape` 必填，目标形状，选择器、元素或原始 path 字符串。`type` 为 `linear`（默认）或 `rotational`；rotational 用角度/长度插值，可避免 morph 中途 kink；linear 效果不对时尝试。`map` 为段匹配方式 `size`（默认）、`position` 或 `complexity`；起止段不对齐时使用；都不行则拆成多个 path 分别 morph。
24. MorphSVG 配置 shapeIndex：偏移起点路径中哪个点映射到终点路径第一个点，避免形状交叉或反转；单段 path 用数字，多段用数组如 `[5, 1, -8]`；负数反转该段；用 `shapeIndex: 'log'` 记录自动计算值后粘贴到 tween；`findShapeIndex(start, end)` 提供交互式 UI 找好值；仅适用于闭合路径。
25. MorphSVG 配置 smooth/curveMode/origin/precision：`smooth`（v3.14+）添加平滑点，数字如 `80`、`auto` 或对象 `{ points: 40 | 'auto', redraw: true | false, persist: true | false }`；`redraw: false` 保留原始锚点（完美保真，间距较不均）；`persist: false` 在 tween 结束时移除添加点；默认 morph 锯齿或不自然时使用。`curveMode`（v3.14+）为布尔值；插值控制柄角度/长度而非原始 x/y，避免曲线 kink；morph 中途 kink 时尝试。`origin` 为 `type: 'rotational'` 的旋转原点；字符串 `50% 50%`（默认）或 `20% 60%, 35% 90%` 为不同起止原点。`precision` 为输出 path 数据小数位，默认 `2`。
26. MorphSVG 配置 precompile/render/updateTarget：`precompile` 为预计算 path 字符串数组（或 `precompile: 'log'` 一次，从 console 复制）；跳过昂贵启动计算，用于非常复杂 morph；仅用于 `<path>`（先转换 polygon/polyline）。`render` 为函数 `(rawPath, target)` 每次更新时调用，如绘制到 canvas；RawPath 是段数组（每段为交替 x,y cubic bezier 坐标数组）。`updateTarget` 在使用 `render`（如仅 canvas）时设为 `updateTarget: false`，不更新原 `<path>`；`MorphSVGPlugin.defaultUpdateTarget` 设置默认。
27. MorphSVG 工具与技巧：`MorphSVGPlugin.convertToPath(selector | element)` 在 DOM 中将 circle/rect/ellipse/line/polygon/polyline 转为 `<path>`；`MorphSVGPlugin.rawPathToString(rawPath)` 和 `stringToRawPath(d)` 在 path 字符串与原始数组间转换；插件在 target 上存原始 `d`（例如 tween 回去：`morphSVG: '#originalId'` 或同一元素）。扭曲或反转 morph 时设置 `shapeIndex`（用 `log` 或 `findShapeIndex()`）；多段路径的 `shapeIndex` 是数组（每段一个值）；只在首帧慢时 precompile；它不修复 tween 期间的 jank（需要简化 SVG 或减小尺寸）。
28. MotionPath：注册 `MotionPathPlugin`；用 `gsap.to('.dot', { duration: 2, motionPath: { path: '#path', align: '#path', alignOrigin: [0.5, 0.5] } })` 沿路径动画。配置：`path` 为 SVG path 元素、选择器或 path 数据字符串；`align` 为要对齐的 path 元素或选择器；`alignOrigin` 为 `[x, y]` 原点（0–1），默认 `[0.5, 0.5]`；`autoRotate` 让元素沿路径切线旋转；`curviness` 为 0–2 路径平滑。
29. MotionPathHelper：注册 `MotionPathPlugin` 和 `MotionPathHelperPlugin`；用 `MotionPathHelper.create('.dot', '#path', { end: 0.5 })` 创建可视化编辑器调整对齐/偏移；调整后在动画中使用 `helper.path` 或 `helper.getProgress()`。
30. CustomEase：注册 `CustomEase`；用 `CustomEase.create('name', '.17,.67,.83,.67')` 创建自定义 easing 曲线（cubic-bezier 或 SVG path）；用 `gsap.to('.el', { x: 100, ease: ease, duration: 1 })` 应用自定义 ease。
31. EasePack：注册 `EasePack` 并使用其额外命名 eases（如 SlowMo、RoughEase、ExpoScaleEase）到 tween 中。
32. CustomWiggle：使用 `CustomWiggle` 实现 wiggle/shake easing，让值多次振荡。
33. CustomBounce：使用 `CustomBounce` 实现可配置强度的 bounce 风格 easing。
34. Physics2D：注册 `Physics2DPlugin`；用 `gsap.to('.ball', { duration: 2, physics2D: { velocity: 250, angle: 80, gravity: 500 } })` 做 2D 物理动画。
35. PhysicsProps：注册 `PhysicsPropsPlugin`；用 `gsap.to('.obj', { duration: 2, physicsProps: { x: { velocity: 100, end: 300 }, y: { velocity: -50, acceleration: 200 } } })` 对属性值应用物理。
36. GSDevTools：注册 `GSDevTools`；用 `GSDevTools.create({ animation: tl })` 创建 UI 用于拖动时间线、切换动画和调试；仅开发使用，不要发布。
37. Pixi：注册 `PixiPlugin`；用 `new PIXI.Sprite(texture)` 创建 Pixi 对象，并用 `gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 })` 动画。
38. 最佳实践：每个使用插件在使用前用 `gsap.registerPlugin()` 注册；布局过渡用 `Flip.getState()` → DOM 改变 → `Flip.from()`；拖拽带动量用 `Draggable` + `InertiaPlugin`；组件 unmount 或元素移除时 revert 插件实例（如 `SplitTextInstance.revert()`）。不要未注册就在 tween 或 API 中使用插件；不要将 GSDevTools 或仅开发插件发布到生产。

适用边界 · 注意事项

• 不要未用 `gsap.registerPlugin()` 注册就在 tween 或 API 中调用插件。
• 不要把 GSDevTools 或仅开发插件发布到生产。
• SplitText 不支持 SVG `<text>`；DrawSVG 只影响 stroke 不影响 fill，且多段 path 可能渲染异常，`<use>` 内容不能视觉更改；ScrollTrigger、核心 tween、React 场景应分别使用 gsap-scrolltrigger、gsap-core、gsap-react 技能。