React-joyride在Next.js本地正常，构建部署后失效且未被纳入构建

可能原因及对应解决办法 #

1. Tree Shaking误剔除组件 #

Next.js生产构建会自动开启Tree Shaking，若组件被判定为"未使用"会被移除：

• 别把react-joyride的导入逻辑放在仅开发环境生效的判断里，比如if (process.env.NODE_ENV === 'development')
• 确认控制组件显示的状态在生产环境下能正常触发，比如不要依赖仅开发环境存在的变量

2. SSR导致组件初始化失败 #

react-joyride依赖DOM环境，SSR时无法正常初始化，进而被构建忽略。改用动态导入并禁用SSR：

import dynamic from 'next/dynamic';

const Joyride = dynamic(() => import('react-joyride'), {
  ssr: false,
  loading: () => null,
});

之后在组件中正常使用Joyride即可。

3. 样式未正确打包（组件存在但不可见） #

如果是样式丢失导致组件看不见，检查以下几点：

• 确保在组件中正确导入样式：import 'react-joyride/lib/react-joyride.css';
• 若使用Tailwind，确认tailwind.config.js的content数组包含了使用Joyride的组件路径，避免样式被PurgeCSS误删

4. 条件渲染逻辑问题 #

检查控制Joyride显示的状态逻辑，避免在服务端直接隐藏组件：

import { useState, useEffect } from 'react';
import Joyride from 'react-joyride';

export default function MyComponent() {
  const [showJoyride, setShowJoyride] = useState(false);

  useEffect(() => {
    // 客户端环境下判断是否显示引导，比如读取本地存储
    const hasSeenTour = localStorage.getItem('hasSeenTour');
    if (!hasSeenTour) {
      setShowJoyride(true);
    }
  }, []);

  return (
    <>
      {/* 页面其他内容 */}
      {showJoyride && (
        <Joyride
          steps={yourStepsConfig}
          onComplete={() => localStorage.setItem('hasSeenTour', 'true')}
        />
      )}
    </>
  );
}

5. 版本兼容性问题（Next.js 13+ App Router） #

如果用的是Next.js 13+的App Router，需要在使用Joyride的组件顶部添加'use client'指令，标记为客户端组件：

'use client';

import Joyride from 'react-joyride';
import 'react-joyride/lib/react-joyride.css';

export default function ClientComponentWithJoyride() {
  // 组件逻辑
}

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