React中使用Three.js开发WebXR应用报错XRWebGLLayer未定义如何解决

报错根因 #

你遇到的'XRWebGLLayer' is not defined no-undef是ESLint校验抛出的编译错误，不是代码逻辑错误：

• 原生JavaScript项目没有配置严格的ESLint全局变量校验，直接调用浏览器内置的WebXR API不会触发报错
• React脚手架默认开启了严格的ESLint校验规则，WebXR相关的全局API不在ESLint默认的浏览器全局变量白名单中，因此会被判定为未定义变量

可选解决方案 #

方案1：临时禁用单行校验（适合快速调试） #

在报错的代码行末尾添加ESLint忽略注释即可：

baseLayer: new XRWebGLLayer(session, gl) // eslint-disable-next-line no-undef

方案2：全局配置ESLint白名单（适合长期开发） #

在项目根目录的.eslintrc.js或.eslintrc.json配置文件中，添加XRWebGLLayer为全局只读变量：

{
  "globals": {
    "XRWebGLLayer": "readonly"
  }
}

配置后重启开发服务，全项目所有用到XRWebGLLayer的位置都不会再触发该报错。

方案3：添加WebXR类型定义（TS项目专属） #

如果你的React项目使用TypeScript开发，还需要安装WebXR的类型声明包：

npm install --save-dev @types/webxr

安装完成后TS即可正常识别所有WebXR相关的全局API类型。

方案4：直接使用Three.js封装的XR能力（推荐新手使用） #

你使用的Three.js 0.133版本已经内置了完整的WebXR封装，不需要手动调用原生XRWebGLLayerAPI，直接用内置XR模块即可：

import * as THREE from 'three';

// 初始化渲染器后开启XR支持
const renderer = new THREE.WebGLRenderer();
renderer.xr.enabled = true;

// 获取到XR会话后直接传给Three.js即可
await renderer.xr.setSession(xrSession);

该方案可以完全规避手动操作原生WebXR API带来的适配、校验问题。

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