React SSR环境下如何渲染Fusion Charts 解决document未定义报错

你遇到的 ReferenceError: document is not defined 报错根因为：Fusion Charts 是纯客户端运行的图表库，内部强依赖浏览器环境的 document、window 全局对象，而 Express 服务端渲染阶段的 Node.js 运行环境不存在这些 API，直接引入初始化就会抛出错误。

以下是可落地的解决方案：

方案1：将图表组件设置为仅客户端渲染（最推荐） #

这类客户端专属组件不需要参与服务端渲染逻辑，直接配置为仅在客户端加载即可，不同技术栈的实现方式如下：

• 自定义 Express + React SSR 场景，可使用 @loadable/component 实现动态引入并关闭SSR：

import loadable from '@loadable/component';

// 动态引入封装好的图表组件，关闭ssr配置
const ChartComponent = loadable(() => import('./YourChartComponent'), {
  ssr: false,
  fallback: <div>图表加载中...</div>
});

// 直接在页面中使用ChartComponent即可，服务端不会渲染该组件

• React 18+ 原生实现，无需额外依赖：

import { useState, useEffect, lazy, Suspense } from 'react';
const ReactFusioncharts = lazy(() => import('react-fusioncharts'));

function ChartContainer() {
  const [isClient, setIsClient] = useState(false);

  // 仅客户端挂载后触发
  useEffect(() => {
    setIsClient(true);
  }, []);

  if (!isClient) return <div>图表加载中...</div>;

  return (
    <Suspense fallback={<div>图表加载中...</div>}>
      <ReactFusioncharts
        type="column2d"
        width="100%"
        height="400"
        dataFormat="JSON"
        dataSource={yourChartConfig}
      />
    </Suspense>
  );
}

方案2：运行环境判断后再初始化依赖 #

不要在组件顶层直接导入 Fusion Charts 相关依赖，将引入和初始化逻辑放在客户端环境判断的分支内：

let ReactFusioncharts = null;
if (typeof window !== 'undefined' && window.document) {
  // 仅客户端环境下执行引入和注册逻辑
  const FusionCharts = require('fusioncharts');
  const Charts = require('fusioncharts/fusioncharts.charts');
  Charts(FusionCharts);
  ReactFusioncharts = require('react-fusioncharts').default;
}

// 组件内使用时先判断ReactFusioncharts是否存在
function ChartComponent() {
  if (!ReactFusioncharts) return <div>图表加载中...</div>;
  return <ReactFusioncharts {/* 图表配置 */} />
}

方案3：服务端Mock浏览器API（不推荐） #

如果有特殊场景需要服务端处理相关逻辑，可以在服务端入口文件给全局对象挂载Mock的window和document，该方案容易产生未知兼容问题，非必要不使用。

注意事项 #

• 不要在组件顶层作用域直接导入 Fusion Charts 相关依赖，避免服务端打包执行时直接触发报错
• 如果使用Webpack打包服务端代码，可在配置中添加externals规则忽略Fusion Charts相关依赖，减少服务端打包体积

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