在React+Astro项目中使用GSAP ScrollTrigger出现模块导入错误

问题重现 #

在Astro框架的React项目中，按照常规方式导入GSAP和ScrollTrigger：

import { useEffect, useRef } from "react";
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

启动开发环境后触发错误：

Cannot use import statement outside a module
Stack Trace
/Applications/MAMP/htdocs/Developer/Git/bitozzi-scale/node_modules/gsap/ScrollTrigger.js:12
import { Observer, _getTarget, _vertical, _horizontal, _scrollers, _proxies, _getScrollFunc, _getProxyProp, _getVelocityProp } from "./Observer.js";
^^^^^^

SyntaxError: Cannot use import statement outside a module
at internalCompileFunction (node:internal/vm:77:18)
at wrapSafe (node:internal/modules/cjs/loader:1288:20)
at Module._compile (node:internal/modules/cjs/loader:1340:27)
at Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
at Module.load (node:internal/modules/cjs/loader:1207:32)
at Module._load (node:internal/modules/cjs/loader:1023:12)
at cjsLoader (node:internal/modules/esm/translators:356:17)
at ModuleWrap. (node:internal/modules/esm/translators:305:7)
at ModuleJob.run (node:internal/modules/esm/module_job:218:25)
at async ModuleLoader.import (node:internal/modules/esm/loader:329:24)

解决方案 #

1. 重装最新版GSAP #

先卸载现有GSAP，重新安装最新稳定版，确保模块结构正确：

npm uninstall gsap
npm install gsap

2. 调整组件内的GSAP使用逻辑 #

GSAP依赖浏览器环境，必须在客户端执行，将插件注册和动画逻辑放在useEffect中，同时添加清理函数避免内存泄漏：

import { useEffect, useRef } from "react";
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

export default function AnimatedComponent() {
  const targetRef = useRef(null);

  useEffect(() => {
    // 仅在客户端注册插件
    gsap.registerPlugin(ScrollTrigger);

    // 初始化滚动动画
    if (targetRef.current) {
      const animation = gsap.from(targetRef.current, {
        y: 60,
        opacity: 0,
        duration: 0.8,
        ease: "power2.out"
      });

      ScrollTrigger.create({
        trigger: targetRef.current,
        start: "top 85%",
        end: "top 15%",
        animation: animation,
        toggleActions: "play reverse play reverse"
      });
    }

    // 组件卸载时清理ScrollTrigger实例
    return () => {
      ScrollTrigger.getAll().forEach(trigger => trigger.kill());
    };
  }, []);

  return <div ref={targetRef} className="animated-element">滚动触发动画的元素</div>;
}

3. 配置Astro的Vite优化规则 #

在astro.config.mjs中添加Vite配置，让Astro正确预编译GSAP的ES模块：

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [react()],
  vite: {
    optimizeDeps: {
      include: ['gsap', 'gsap/ScrollTrigger']
    }
  }
});

4. 标记React组件为客户端组件 #

如果是在.astro页面文件中引入React组件，必须添加客户端指令（如client:load），确保组件在浏览器中运行：

---
import AnimatedComponent from '../components/AnimatedComponent.jsx';
---

<AnimatedComponent client:load />

错误原因 #

该错误是因为Node.js的CommonJS模块加载器尝试解析GSAP内部的ES模块语法（import语句），而Astro的服务端渲染环境默认使用CommonJS处理模块。通过上述配置，让Vite预编译GSAP为兼容格式，并确保GSAP代码仅在客户端执行，即可解决模块冲突问题。

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