Next.js集成ScrollReveal遇ReferenceError: document未定义问题求助

这个错误的核心原因是ScrollReveal库在静态导入阶段就会访问浏览器的document对象，而Next.js的服务端渲染(SSR)环境中不存在document，所以即使在useEffect里做环境判断，也会在导入环节就触发报错。以下是两种可行的解决方案：

方案一：在useEffect中动态导入ScrollReveal #

通过动态导入(import())延迟库的加载时机，确保只有在客户端环境下才加载并初始化ScrollReveal：

import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    let scrollRevealInstance;

    // 动态加载并初始化ScrollReveal
    const initScrollReveal = async () => {
      const ScrollReveal = (await import('scrollreveal')).default;
      scrollRevealInstance = ScrollReveal();
      
      scrollRevealInstance.reveal('.my-element', {
        // 自定义配置示例
        origin: 'bottom',
        distance: '30px',
        duration: 800,
        delay: 150,
        reset: false
      });
    };

    initScrollReveal();

    // 组件卸载时清理实例，避免内存泄漏
    return () => {
      if (scrollRevealInstance) {
        scrollRevealInstance.destroy();
      }
    };
  }, []);

  return (
    <div className="my-element">
      {/* 组件内容 */}
    </div>
  );
}

export default MyComponent;

方案二：禁用组件的服务端渲染(SSR) #

使用Next.js的dynamic工具导入组件，强制组件仅在客户端渲染，从根源避免服务端访问DOM：

步骤1：修改组件导入方式（在父组件中） #

import dynamic from 'next/dynamic';

// 禁用SSR，组件仅在客户端加载
const MyComponent = dynamic(() => import('./MyComponent'), {
  ssr: false,
  // 可选：设置加载时的占位内容
  loading: () => <div>加载中...</div>
});

步骤2：原组件可保留静态导入 #

import { useEffect } from 'react';
import ScrollReveal from 'scrollreveal';

function MyComponent() {
  useEffect(() => {
    const sr = ScrollReveal();
    sr.reveal('.my-element', { /* 配置选项 */ });

    return () => sr.destroy();
  }, []);

  return (
    <div className="my-element">
      {/* 组件内容 */}
    </div>
  );
}

export default MyComponent;

关键注意事项 #

• 动态导入时需处理异步逻辑，确保库加载完成后再初始化
• 组件卸载时务必调用sr.destroy()清理ScrollReveal实例，防止内存泄漏
• 确保目标DOM元素的class在客户端渲染时已存在，避免ScrollReveal找不到元素

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