Next.js使用MUI useMediaQuery首渲染样式闪烁如何解决

闪烁的核心原因是服务端渲染阶段无法获取客户端真实视口宽度，useMediaQuery 返回的默认值和客户端hydration后拿到的实际值不一致，触发DOM属性更新导致样式跳变。以下是可直接落地的修复方案，按推荐优先级排序：

1. 全局配置SSR默认匹配值（最优方案，零业务代码侵入） #

这个方案从框架层面统一SSR和客户端首次渲染的返回值，不需要修改现有业务组件的写法，也不会损失SSR的SEO收益。
实现逻辑是在服务端接收请求时，通过请求头的User-Agent初步判断设备类型，给所有useMediaQuery调用设置统一的默认匹配值，保证SSR输出的DOM结构和客户端首次hydration时的结构完全一致，从根源消除hydration不匹配问题。
以Pages Router为例，在_app.jsx中做如下配置：

import App from 'next/app';
import { createTheme, ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

export default function MyApp({ Component, pageProps, isMobile }) {
  const theme = createTheme({
    // 原有主题配置、断点配置保持不变
    components: {
      MuiUseMediaQuery: {
        defaultProps: {
          // md断点以下的默认匹配值和UA判断结果对齐
          defaultMatches: isMobile
        }
      }
    }
  });

  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

MyApp.getInitialProps = async (appContext) => {
  const appProps = await App.getInitialProps(appContext);
  const req = appContext.ctx.req;
  const userAgent = req ? req.headers['user-agent'] : '';
  // 移动端UA判断正则，可根据业务需求调整
  const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent);
  return { ...appProps, isMobile };
}

配置完成后，原有const matches = useMediaQuery(theme.breakpoints.down('md'))的逻辑不需要做任何修改，首屏不会再出现闪烁。

2. 局部组件客户端渲染兜底（适合非核心内容场景） #

如果只是个别组件有这个问题，且组件内容不要求首屏SSR输出，可以用MUI自带的NoSsr组件包裹响应式逻辑部分，让这部分内容等客户端JS加载完成后再渲染，绕开SSR和客户端的返回值差异：

import NoSsr from '@mui/material/NoSsr';
import Typography from '@mui/material/Typography';
import { useTheme } from '@mui/material/styles';
import useMediaQuery from '@mui/material/useMediaQuery';

export default function TextBlock({ text }) {
  const theme = useTheme();
  const matches = useMediaQuery(theme.breakpoints.down('md'));
  return (
    // fallback填SSR阶段默认渲染的内容，一般填桌面端样式即可
    <NoSsr fallback={<Typography variant="h5">{text}</Typography>}>
      <Typography variant={matches ? 'subtitle1' : 'h5'}>
        {text}
      </Typography>
    </NoSsr>
  )
}

注意这个方案会导致包裹的内容不参与服务端渲染，如果是核心文本、首屏关键内容不建议使用，会影响SEO和首屏内容加载速度。

3. 用MUI原生响应式属性替代手动useMediaQuery判断（最简洁写法） #

写两个组件切换display的方式属于冗余写法，实际上MUI v5.14.0及以上版本已经支持所有组件属性直接传入断点配置对象，不需要手动调用useMediaQuery做判断，底层已经处理了SSR一致性问题，不会出现闪烁：

// 不需要引入useMediaQuery，直接给variant传断点配置即可
<Typography variant={{ xs: 'subtitle1', md: 'h5' }}>
  {text}
</Typography>

如果MUI版本低于v5.14.0，也可以通过sx属性控制响应式样式，同样不需要写重复组件。

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