React Static中使用react-tooltip遇SSR不支持问题求解决方案

我之前也碰到过react-tooltip在SSR框架里的报错问题，你用typeof document === "undefined"返回null的思路是对的，但大概率是组件导入或执行时机的问题导致没生效，下面分享几个亲测有效的解决办法：

方法1：仅在客户端动态导入组件 #

问题的核心是SSR阶段加载了react-tooltip，而它的内部代码会尝试访问浏览器API，所以我们可以让组件只在客户端环境下才导入，彻底避免SSR执行到它的代码：

import React, { lazy, Suspense } from 'react';
import IconInfoSmall from './your-icon-path';

// 仅在客户端环境加载ReactTooltip
const ReactTooltip = lazy(() => 
  import('react-tooltip').then(module => ({ default: module.default }))
);

function YourTooltipComponent({ tooltipId, small }) {
  // SSR阶段直接返回触发元素的占位
  if (typeof window === 'undefined') {
    return <span><IconInfoSmall /></span>;
  }

  return (
    <Suspense fallback={<span><IconInfoSmall /></span>}>
      <div className="inline-flex text-grey-darker">
        <span data-tip data-for={tooltipId}>
          <IconInfoSmall />
        </span>
        <ReactTooltip 
          id={tooltipId} 
          effect="solid" 
          type="light" 
          border 
          borderColor="#969696" 
          className={`info-tooltip ${small ? 'w-60' : 'w-90'}`} 
          clickable 
        />
      </div>
    </Suspense>
  );
}

方法2：升级到支持SSR的react-tooltip版本 #

如果你用的是旧版react-tooltip（比如v4及以下），建议直接升级到v5+版本，官方已经原生支持SSR了。升级后只需要在客户端专属的入口文件（比如React Static的src/index.js）里做一次初始化：

// 客户端入口文件
import ReactTooltip from 'react-tooltip';

// 确保只在客户端执行初始化
if (typeof window !== 'undefined') {
  ReactTooltip.rebuild();
}

之后组件里就可以正常使用，不需要额外判断document了，新版会自动跳过SSR阶段的DOM操作。

方法3：用useEffect控制客户端渲染 #

利用React的useEffect只在客户端执行的特性，延迟渲染react-tooltip组件：

import React, { useState, useEffect } from 'react';
import ReactTooltip from 'react-tooltip';
import IconInfoSmall from './your-icon-path';

function YourTooltipComponent({ tooltipId, small }) {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
    // 组件挂载后初始化tooltip
    ReactTooltip.rebuild();
  }, []);

  // SSR阶段只渲染触发图标
  if (!isClient) {
    return <span><IconInfoSmall /></span>;
  }

  return (
    <div className="inline-flex text-grey-darker">
      <span data-tip data-for={tooltipId}>
        <IconInfoSmall />
      </span>
      <ReactTooltip 
        id={tooltipId} 
        effect="solid" 
        type="light" 
        border 
        borderColor="#969696" 
        className={`info-tooltip ${small ? 'w-60' : 'w-90'}`} 
        clickable 
      />
    </div>
  );
}

为什么你的原方法没生效？ #

很大可能是因为你在组件顶部就导入了ReactTooltip，即使你在渲染阶段返回null，导入时react-tooltip的内部代码已经尝试访问document了，导致SSR报错。所以关键是要让react-tooltip的代码完全不进入SSR的执行流程，或者用新版的兼容方案。

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