React项目使用screenfull刷新报ReferenceError: document is not defined如何解决

架构老林

2026-9-23

React项目使用screenfull库刷新报错ReferenceError: document is not defined的解决方案

报错原因

这个错误的核心是screenfull库的初始化逻辑会直接访问浏览器端的document对象，而你的项目在服务端渲染（SSR/SSG）阶段就加载执行了该库的代码，服务端运行环境不存在document对象，因此抛出异常。

热更新时正常是因为热更新仅在客户端侧执行，此时已经有完整的浏览器环境
全局刷新时会先走服务端渲染逻辑，直接引入的screenfull在服务端执行就会触发报错

排查步骤

先确认项目是否使用了SSR/SSG框架（如Next.js、Gatsby），或配置了预渲染相关插件
检查screenfull的引入位置，是否是在组件/文件的顶层直接通过import语句引入

解决方案

通用方案（适配所有React项目，包括SSR场景）：将screenfull的引入逻辑放到仅客户端执行的生命周期中，推荐在useEffect中动态引入：

import { useEffect, useState } from 'react';

function FullscreenComponent() {
  // 存储screenfull实例
  const [screenfull, setScreenfull] = useState(null);

  useEffect(() => {
    // useEffect仅在客户端执行，此时存在document对象
    const loadScreenfull = async () => {
      const sfModule = await import('screenfull');
      setScreenfull(sfModule.default);
    };
    loadScreenfull();
  }, []);

  const toggleFullscreen = () => {
    // 调用前先判断实例存在且全屏功能可用
    if (screenfull?.isEnabled) {
      screenfull.toggle();
    }
  };

  return <button onClick={toggleFullscreen}>切换全屏</button>;
}

如果是Next.js项目，也可以使用next/dynamic配置禁用SSR来引入：

import dynamic from 'next/dynamic';

// 动态引入screenfull，关闭服务端渲染
const Screenfull = dynamic(() => import('screenfull'), {
  ssr: false,
  loading: () => null
});