React Native使用@microsoft/signalr报错ReferenceError: document is not defined

ReferenceError: document is not defined 报错说明当前代码运行环境不存在浏览器专属的全局对象document，SignalR默认客户端包依赖浏览器环境内置的document、window对象，触发该报错的常见场景包括：

• 项目使用SSR/SSG框架（Next.js、Nuxt.js等），连接创建逻辑在服务端渲染阶段执行
• 代码运行在非浏览器环境：Node.js服务端、微信小程序、App端定制webview环境等
• 近期升级了SignalR客户端版本，新版本新增了对document对象的依赖逻辑

场景1：SSR/SSG框架环境 #

确保连接创建、start调用的逻辑仅在客户端侧执行：

• React/Next.js项目：将createConnection调用放到useEffect回调中，或者用dynamic导入相关组件时关闭SSR：

// 示例：Next.js 组件中调用
useEffect(() => {
  createConnection()
  // 组件卸载时销毁连接
  return () => {
    _hubConnection?.stop()
  }
}, [])

• Vue/Nuxt项目：将createConnection调用放到onMounted钩子中，或者用<client-only>标签包裹相关业务组件。

场景2：非浏览器端运行环境 #

替换对应环境适配的SignalR客户端包：

• Node.js环境：引入@microsoft/signalr包的无浏览器依赖入口：

import * as signalR from '@microsoft/signalr/dist/esm/index.js'

• 小程序/APP定制环境：使用对应平台适配的SignalR第三方包，避免使用默认的浏览器端版本。

临时兼容方案 #

可在代码最顶部添加全局对象polyfill，临时规避报错，仅建议用于验证问题：

globalThis.document = globalThis.document || {}

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