Next.js 安装 DetectRTC 包引发服务器内部错误：HMR崩溃且报document未定义

阿华AIGC实验室

2026-4-22

看起来你遇到了Next.js服务端渲染（SSR）和依赖浏览器API的第三方包之间的典型冲突问题，别着急，咱们来一步步拆解解决。

问题根源分析

Next.js在开发模式下会同时进行服务端渲染和客户端渲染，而DetectRTC这个包很可能在模块加载阶段就直接访问了document、window这类仅存在于浏览器环境的对象——这就导致服务端渲染时找不到这些对象，进而触发styled-jsx的报错（错误栈指向styled-jsx只是表象，本质是浏览器API在服务端被调用了）。你之前尝试的动态导入和window检查可能没做到位，所以没解决问题。

可行解决方案

1. 用Next.js动态导入强制禁用SSR

确保使用DetectRTC的组件完全在客户端渲染，给动态导入加上ssr: false配置：

import dynamic from 'next/dynamic';

// 导入你的DetectRTC组件，禁用服务端渲染
const RTCChecker = dynamic(() => import('../components/RTCChecker'), {
  ssr: false,
  loading: () => <p>正在检测设备...</p>
});

// 在页面中使用这个组件
export default function Home() {
  return (
    <div>
      <h1>设备检测</h1>
      <RTCChecker />
    </div>
  );
}

2. 在组件内部延迟初始化DetectRTC

如果是直接在组件里使用DetectRTC，一定要把初始化逻辑放在useEffect中（useEffect仅在客户端执行），同时结合动态导入：

import { useEffect, useState } from 'react';

export default function RTCChecker() {
  const [deviceStatus, setDeviceStatus] = useState(null);

  useEffect(() => {
    // 仅在客户端环境加载并初始化DetectRTC
    const initDetectRTC = async () => {
      // 动态导入DetectRTC
      const DetectRTC = (await import('detectrtc')).default;
      DetectRTC.load(() => {
        setDeviceStatus({
          hasWebcam: DetectRTC.hasWebcam,
          hasMicrophone: DetectRTC.hasMicrophone,
          hasSpeakers: DetectRTC.hasSpeakers
        });
      });
    };

    initDetectRTC();
  }, []);

  if (!deviceStatus) {
    return <p>正在检测摄像头、麦克风状态...</p>;
  }

  return (
    <div className="device-status">
      <p>摄像头：{deviceStatus.hasWebcam ? '✅ 可用' : '❌ 不可用'}</p>
      <p>麦克风：{deviceStatus.hasMicrophone ? '✅ 可用' : '❌ 不可用'}</p>
      <p>扬声器：{deviceStatus.hasSpeakers ? '✅ 可用' : '❌ 不可用'}</p>
    </div>
  );
}