Next.js中使用intro.js-react遇ReferenceError: Element未定义问题求助

问题根源 #

Next.js默认的服务端渲染（SSR）环境中不存在浏览器的Element全局对象，而intro.js-react的底层依赖代码在服务端执行时尝试访问该对象，导致报错。首次刷新触发SSR渲染所以报错，注释组件后刷新进入客户端 hydration 阶段，此时取消注释组件在浏览器环境运行，因此能正常工作。

解决方案 #

1. 动态导入组件并禁用SSR

使用Next.js的dynamic导入方法，强制组件仅在客户端渲染：

import { useState } from 'react';
import dynamic from 'next/dynamic';

// 动态加载Steps组件，禁用服务端渲染
const Steps = dynamic(() => import('intro.js-react').then(mod => mod.Steps), {
  ssr: false,
  loading: () => null // 可选，加载时的占位内容
});

export default function Dashboard() {
  const [stepEnabled, setStepEnabled] = useState(true);
  const steps = [
    {
      intro: 'Welcome to WorkStats!'
    }
  ];
  const onExit = () => {
    setStepEnabled(false);
  };

  return (
    <main>
      <Steps
        enabled={stepEnabled}
        steps={steps}
        initialStep={0}
        onExit={onExit}
      />
      <div>Test</div>
    </main>
  );
}

2. 条件渲染，仅在客户端加载组件

通过判断window对象是否存在，确保组件只在浏览器环境渲染：

import { useState } from 'react';
import { Steps } from 'intro.js-react';

export default function Dashboard() {
  const [stepEnabled, setStepEnabled] = useState(true);
  const steps = [
    {
      intro: 'Welcome to WorkStats!'
    }
  ];
  const onExit = () => {
    setStepEnabled(false);
  };

  // 检测是否处于客户端环境
  const isClient = typeof window !== 'undefined';

  return (
    <main>
      {isClient && (
        <Steps
          enabled={stepEnabled}
          steps={steps}
          initialStep={0}
          onExit={onExit}
        />
      )}
      <div>Test</div>
    </main>
  );
}

3. 检查并更新依赖版本

确认intro.js和intro.js-react版本兼容，尝试更新到最新稳定版：

npm update intro.js intro.js-react
# 或使用yarn
yarn upgrade intro.js intro.js-react

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