Next.js项目npm run build报navigator未定义，dev模式正常

问题根源 #

即使给页面添加了'use client'指令，Next.js执行npm run build时仍会对客户端组件进行静态预渲染——这个过程在Node.js环境中完成，而Node.js没有浏览器专属的navigator对象。如果组件在顶层代码（比如初始化、变量声明阶段）直接访问navigator，预渲染时就会抛出错误。

解决方案 #

方案1：用useEffect延迟访问navigator

useEffect的回调仅在客户端浏览器环境执行，预渲染阶段不会触发，将依赖navigator的逻辑放在这里：

'use client';
import { useEffect, useState } from 'react';

export default function SaloonServices() {
  const [deviceInfo, setDeviceInfo] = useState({});

  useEffect(() => {
    // 此处访问navigator是安全的
    const userAgent = navigator.userAgent;
    const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent);
    setDeviceInfo({ userAgent, isMobile });
  }, []);

  return (
    <div>
      {deviceInfo.isMobile ? (
        <p>当前为移动设备</p>
      ) : (
        <p>当前为桌面设备</p>
      )}
    </div>
  );
}

方案2：处理第三方依赖的提前调用

如果页面使用的第三方库在导入/初始化阶段就访问了navigator，需通过动态导入确保依赖只在客户端加载：

'use client';
import { useEffect, useState } from 'react';

export default function SaloonServices() {
  const [ThirdPartyComponent, setThirdPartyComponent] = useState(null);

  useEffect(() => {
    // 动态导入依赖，避免预渲染时执行库的初始化代码
    import('your-third-party-lib').then(module => {
      setThirdPartyComponent(module.YourComponent);
    });
  }, []);

  // 加载完成前显示占位内容
  if (!ThirdPartyComponent) {
    return <div>加载中...</div>;
  }

  return (
    <div>
      <ThirdPartyComponent />
    </div>
  );
}

方案3：用typeof判断navigator是否存在

直接访问navigator前先判断其是否存在，避免预渲染阶段报错：

'use client';

export default function SaloonServices() {
  // 仅在客户端环境中访问navigator
  const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : false;

  return (
    <div>
      {isOnline ? <span>在线</span> : <span>离线</span>}
    </div>
  );
}

核心原则 #

把所有依赖浏览器API的代码放在客户端专属执行时机（比如useEffect回调、动态导入后、存在性判断后），避免预渲染阶段（Node.js环境）执行到这些代码。

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