控制台报Uncaught ReferenceError: gsap is not defined错误求助

架构老林

2026-9-29

错误原因排查

GSAP资源未成功加载：网络故障、广告拦截类浏览器插件、CDN节点不可用都可能导致gsap.min.js加载失败，全局window对象上没有挂载gsap实例，调用时就会触发引用错误。
脚本执行顺序异常：即使你将GSAP的script标签放在业务JS之前，如果业务JS设置了async属性、是动态插入到页面的，或者GSAP资源加载慢于业务JS，都会导致业务代码执行时gsap还未完成初始化。
模块化环境全局变量缺失：如果你的业务JS是在ES Module、CommonJS等模块化环境下打包运行的，没有将gsap暴露到全局作用域，直接调用全局gsap也会触发该错误。
注意：你代码中使用了ScrollTrigger插件，GSAP核心包不包含该插件，解决当前报错后如果未单独引入ScrollTrigger，会触发ScrollTrigger is not defined错误。

解决方案

验证资源加载状态
打开浏览器开发者工具的「网络」面板，筛选JS类资源，查看gsap.min.js的加载状态。如果加载失败，可更换CDN源或者将资源下载到本地引入。
保证脚本执行顺序
给业务JS添加defer属性，确保所有前置脚本加载完成后再执行业务代码，同时补充引入ScrollTrigger插件的CDN：

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.8.0/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.8.0/ScrollTrigger.min.js"></script>
<script src="js/index.min.js" defer></script>

也可以将所有script标签放在</body>闭合标签之前，自然保证执行顺序。
3. 模块化环境适配
如果项目使用Vue、React、Webpack等模块化开发，优先通过npm安装GSAP：
安装命令：npm install gsap
业务代码中按需引入使用：

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

gsap.registerPlugin(ScrollTrigger);
// 后续动画逻辑

增加兼容校验
调用gsap前先判断实例是否存在，避免报错阻塞页面其他逻辑执行：

if (window.gsap && window.ScrollTrigger) {
  gsap.registerPlugin(ScrollTrigger);
  gsap.to('.laptop__top', {
    scrollTrigger: {
        trigger: '.laptop',
        start: '20px top',
        end: '250px top',
        scrub: 2.5,
    },
    rotationX: 0,
    duration: 5,
  });
}

内容的提问来源于stack exchange，提问作者Roman Vinichenko