GSAP ScrollTrigger插件导入注册失败，DOM元素无动画求助

问题现象 #

• console.log(gsap.plugins)（注：应为复数plugins）中无ScrollTrigger属性
• 所有DOM元素无法触发滚动动画
• 浏览器反复弹出警告：Invalid property set to Missing plugin? gsap.registerPlugin()

环境与代码信息 #

导入与注册代码 #

import gsap from "gsap"
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

TypeScript配置 #

{
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "allowJs": true,

    /* Bundler mode */
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "jsx": "react-jsx",
    "outDir": "./dist"
}

已尝试方案 #

• 安装useGSAP钩子替代useLayoutEffect
• 尝试{ gsap }和{ ScrollTrigger }解构导入
• 在index.html中引入CDN脚本：

<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/ScrollTrigger.min.js"></script>

依赖版本 #

gsap版本：^3.12.5

解决方案 #

• 移除重复导入：同时使用npm包和CDN脚本会生成两个独立GSAP实例，注册的ScrollTrigger仅对其中一个生效。请删除index.html中的CDN脚本，保留npm包导入方式。
• 提前注册时机：在项目入口文件（如main.tsx/index.ts）中执行gsap.registerPlugin(ScrollTrigger)，确保在所有动画逻辑运行前完成插件注册。
• 修正导入写法：针对TS环境，尝试默认导入ScrollTrigger：

import gsap from "gsap";
import ScrollTrigger from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

• 禁用Tree Shaking误删：在打包工具配置中显式保留ScrollTrigger代码。以Vite为例，在vite.config.ts的optimizeDeps.include中添加"gsap/ScrollTrigger"。
• 重装依赖验证：卸载并重新安装GSAP包，排除依赖损坏问题：

npm uninstall gsap
npm install gsap@3.12.5

• 检查类型声明：GSAP 3.x自带类型声明，若安装了旧版@types/gsap请删除，避免类型冲突导致隐性错误。

内容的提问来源于stack exchange，提问作者nic-ole