You need to enable JavaScript to run this app. Next.js中如何基于屏幕宽度实现组件条件渲染并规避window引用报错
优惠活动
大模型
产品
解决方案
定价
更多

Next.js中如何基于屏幕宽度实现组件条件渲染并规避window引用报错

Next.js 下基于屏幕宽度的组件条件渲染可行方案

原有纯客户端视口判断逻辑迁移到Next.js时报错的核心原因,是服务端渲染阶段不存在window全局对象,所有可行方案的核心思路都是避开服务端执行阶段对window的引用,同时兼顾水合一致性与渲染性能。

方案1:客户端组件挂载后读取视口宽度(最常用)

利用React的useEffect执行时机——该钩子仅在客户端水合完成后触发,此时已经具备完整的window全局环境,完全不会触发服务端阶段的引用报错。
实现代码参考:

'use client' // App Router 下需标识为客户端组件,Pages Router 页面默认具备客户端执行能力
import { useState, useEffect } from 'react'

const MOBILE_BREAKPOINT = 576

function ResponsiveContainer() {
  // 初始值保持服务端与客户端首次渲染完全一致,避免水合结构不匹配的警告
  const [isMobile, setIsMobile] = useState(false)

  useEffect(() => {
    const handleResize = () => {
      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
    }
    // 挂载后立刻读取一次真实视口宽度
    handleResize()
    // 绑定视口尺寸变化监听
    window.addEventListener('resize', handleResize)
    // 组件卸载时清理监听,避免内存泄漏
    return () => window.removeEventListener('resize', handleResize)
  }, [])

  return (
    <div>
      {isMobile ? <ComponentA /> : <ComponentB />}
    </div>
  )
}

注意事项:

  • 不要在useState初始化阶段直接引用window,否则会在服务端执行时直接报错
  • 必须在组件卸载时移除事件监听,避免长时间运行出现性能问题

方案2:纯CSS媒体查询控制渲染(无JS兼容问题)

如果不需要在JS层面根据视口尺寸做业务逻辑判断,只需要做组件的显示/隐藏,完全可以跳过JS读取视口的逻辑,直接利用浏览器原生的CSS媒体查询实现:

// 无客户端交互逻辑,可直接在服务端组件中使用
function ResponsiveContainer() {
  return (
    <div>
      {/* 仅在小于576px视口下显示移动端组件 */}
      <div className="block sm:hidden">
        <ComponentA />
      </div>
      {/* 仅在大于等于576px视口下显示桌面端组件 */}
      <div className="hidden sm:block">
        <ComponentB />
      </div>
    </div>
  )
}

方案优势:

  • 无任何服务端兼容问题,首屏渲染无组件闪跳,体验最优
  • 无需额外的JS监听逻辑,性能开销最低
    方案局限:
  • 两份组件都会被渲染到DOM中,对于重型组件会增加不必要的前端加载体积

方案3:动态导入跳过服务端渲染(重型组件适配)

如果是体积较大的组件,不想在服务端渲染阶段加载对应代码,可以借助Next.js提供的next/dynamic配置ssr: false,让组件完全只在客户端加载渲染,此时就可以放心在客户端逻辑中引用window对象。
实现代码参考:

'use client'
import { useState, useEffect } from 'react'
import dynamic from 'next/dynamic'

// 跳过服务端渲染,仅在客户端环境加载目标组件
const ComponentA = dynamic(() => import('./ComponentA'), {
  ssr: false,
  loading: () => <div>加载中...</div>
})
const ComponentB = dynamic(() => import('./ComponentB'), {
  ssr: false,
  loading: () => <div>加载中...</div>
})

function ResponsiveContainer() {
  // 由于配置了ssr: false,这段初始化逻辑只会在客户端执行,不会触发服务端的window引用错误
  const [isMobile, setIsMobile] = useState(() => window.innerWidth < 576)

  useEffect(() => {
    const handleResize = () => setIsMobile(window.innerWidth < 576)
    window.addEventListener('resize', handleResize)
    return () => window.removeEventListener('resize', handleResize)
  }, [])

  return (
    <div>
      {isMobile ? <ComponentA /> : <ComponentB />}
    </div>
  )
}

注意事项:

  • 配置ssr: false的动态导入逻辑不能直接放在服务端组件顶层,需要在客户端组件内使用
  • 组件在客户端加载阶段会出现占位闪屏,需要搭配合适的加载态提示优化体验

性能优化提示:日常使用时可以将全局resize监听替换为原生window.matchMedia接口,比直接监听resize事件的性能表现更好,示例写法:

const mediaQuery = window.matchMedia('(max-width: 575px)')
const handleMediaChange = (e) => setIsMobile(e.matches)
mediaQuery.addEventListener('change', handleMediaChange)
// 组件卸载时对应移除该监听即可

内容的提问来源于stack exchange,提问作者Diego

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.04 12:15:04