GatsbyJs结合Material-UI页面刷新CSS丢失渲染异常问题

算力阿峰

2026-8-26

问题根本原因

Gatsby生产构建走静态生成/服务端渲染逻辑，整个构建过程在Node.js环境运行，不存在浏览器的window对象。你代码里初始状态硬编码mobileView: true，导致构建出来的首屏HTML永远按移动端结构生成。页面刷新时浏览器会先解析渲染这份静态HTML，等JS加载完成进入hydration阶段才会执行useEffect里的视口判断逻辑切换桌面端视图，这个切换过程就会出现样式闪烁、渲染错乱；开发模式下gatsby develop以客户端实时编译渲染为主，几乎不触发SSR逻辑，所以本地开发时无法复现问题。
resize事件绑定存在逻辑bug：绑定和解绑时都传入了新创建的匿名箭头函数，removeEventListener无法匹配到之前注册的监听函数，会导致内存泄漏、状态重复触发更新，进一步放大渲染异常。
MobileMenu和DesktopHeader定义在Header组件内部，每次Header重渲染都会生成两个组件的全新引用，导致React反复卸载、重挂载子组件，也会加剧样式错乱问题。
如果使用Material UI这类CSS-in-JS库，未做SSR适配时会出现服务端生成的样式和客户端注入的样式优先级不匹配问题，直接表现为刷新页面时CSS样式丢失。

修复方法

修正响应式状态初始化逻辑，兼容SSR环境，在客户端首屏渲染前就拿到正确的视口宽度，避免hydration前后状态不一致。
修复resize事件绑定逻辑，绑定和解绑使用同一个函数引用，保证组件卸载时可以正确清除监听。
将MobileMenu、DesktopHeader移到Header组件外部定义，避免组件重渲染时重复创建子组件引用。
如果使用Material UI，安装适配插件gatsby-plugin-material-ui并在gatsby-config.js中配置，解决SSR阶段样式注入顺序错误的问题；也可以直接使用MUI自带的useMediaQuery钩子替代手写的视口判断逻辑，这个钩子已经内置了SSR兼容、监听节流优化，稳定性远高于手写实现。

修复后的核心代码参考：

// 子组件移到Header外部定义，避免重渲染时重复创建组件引用
const MobileMenu = () => {...some code}
const DesktopHeader = () => {...some code}

export default function Header(props) {
  const classes = useStyles()
  // 初始化时判断运行环境，客户端首屏就拿到正确的视口状态
  const [mobileView, setMobileView] = useState(() => {
    if (typeof window === 'undefined') return true
    return window.innerWidth < 900
  })

  useEffect(() => {
    const setResponsiveness = () => {
      setMobileView(window.innerWidth < 900)
    }
    setResponsiveness()
    // 绑定和移除使用同一个函数引用，保证监听能被正确清除
    window.addEventListener("resize", setResponsiveness)
    return () => {
      window.removeEventListener("resize", setResponsiveness)
    }
  }, [])

  return (
    <header>
      <AppBar className={classes.root} elevation={0} position='static'>
        {mobileView ? <MobileMenu /> : <DesktopHeader />}
      </AppBar>
    </header>
  )
}

如果用MUI的useMediaQuery简化实现，可以直接替换掉手写的监听逻辑，代码更简洁：

import useMediaQuery from '@mui/material/useMediaQuery'

const MobileMenu = () => {...some code}
const DesktopHeader = () => {...some code}

export default function Header(props) {
  const classes = useStyles()
  // 自动处理SSR兼容、resize监听和节流逻辑
  const mobileView = useMediaQuery('(max-width:899px)')

  return (
    <header>
      <AppBar className={classes.root} elevation={0} position='static'>
        {mobileView ? <MobileMenu /> : <DesktopHeader />}
      </AppBar>
    </header>
  )
}

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