Next.js 13+ 移动端设备检测渲染组件问题求助

问题根源 #

直接在组件初始化时调用 isMobile() 会触发错误，因为 Next.js 默认的服务端渲染（SSR）/静态生成（SSG）阶段不存在 window 对象，而 ismobilejs 依赖该对象运行。即使添加了 use client，如果执行时机不对，仍然会在服务端或 hydration 阶段触发错误。

修复步骤及代码示例 #

1. 标记为客户端组件 + 延迟执行检测逻辑

将 use client 放在文件最顶部（必须是文件第一行，注释除外），并通过 useState + useEffect 在客户端挂载后再执行设备检测：

"use client";
import useTranslation from "next-translate/useTranslation";
import isMobile from "ismobilejs";
import { useEffect, useState } from "react";
import DefaultLayout from "../../components/core/Layouts/Default";
import { MouseIcon, ScrollDownWrapper, ScrollText, SearchBoxWrapper, SliderWrapper, Wrapper } from "./style";
import MainSlider from "../../components/common/MainSlider";
import SearchBox from "../../components/common/SearchBox";

const HomeScreen = () => {
    const { t } = useTranslation("home");
    const [isMobileDevice, setIsMobileDevice] = useState(false);

    useEffect(() => {
        // 仅在客户端环境执行，此时 window 已存在
        setIsMobileDevice(isMobile()?.any);
        
        // 可选：监听窗口大小变化，动态更新设备状态（比如平板旋转场景）
        const handleResize = () => {
            setIsMobileDevice(isMobile()?.any);
        };
        window.addEventListener("resize", handleResize);
        
        return () => window.removeEventListener("resize", handleResize);
    }, []);

    return (
        <DefaultLayout>
            <Wrapper>
                <SearchBoxWrapper>
                    <SearchBox />
                    {isMobileDevice && (
                        <ScrollDownWrapper>
                            <MouseIcon />
                            <ScrollText>{t("scrollDown")}</ScrollText>
                        </ScrollDownWrapper>
                    )}
                </SearchBoxWrapper>
                <SliderWrapper>
                    <MainSlider />
                </SliderWrapper>
            </Wrapper>
        </DefaultLayout>
    );
};

export default HomeScreen;

2. 可选方案：移除第三方依赖，直接用媒体查询

如果不想依赖 ismobilejs，可以用原生 window.matchMedia 实现设备检测，减少依赖同时更灵活：

"use client";
import useTranslation from "next-translate/useTranslation";
import { useEffect, useState } from "react";
// ...其他导入

const HomeScreen = () => {
    const { t } = useTranslation("home");
    const [isMobileDevice, setIsMobileDevice] = useState(false);

    useEffect(() => {
        // 自定义移动端断点（比如 768px）
        const mobileQuery = window.matchMedia("(max-width: 768px)");
        
        // 初始化状态
        setIsMobileDevice(mobileQuery.matches);
        
        // 监听断点变化
        const handleQueryChange = (e) => {
            setIsMobileDevice(e.matches);
        };
        mobileQuery.addEventListener("change", handleQueryChange);
        
        return () => mobileQuery.removeEventListener("change", handleQueryChange);
    }, []);

    // ...返回部分与之前一致
};

关键说明 #

• use client 必须放在文件第一行，否则 Next.js 不会将该组件视为客户端组件，服务端仍会执行初始化代码。
• 所有依赖 window 的逻辑必须放在 useEffect/useLayoutEffect 中，确保仅在客户端挂载后执行。
• 添加窗口大小/媒体查询监听是为了适配动态场景（比如窗口缩放、设备旋转），如果不需要可以省略。

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