Deck.gl在Vite开发模式下报TypeError: Cannot set properties of undefined (setting 'adapter')

问题背景 #

React + Deck.gl + Vite项目，已上线生产环境，之前运行正常。本地开发用vite启动服务器时出现以下报错：

TypeError: Cannot set properties of undefined (setting 'adapter') at new WebGLAdapter

已尝试回滚代码、重新拉取生产分支、删除node_modules并通过原yarn.lock重装依赖，均无效。其他关键现象：

• Chrome、Safari中均报错，但预发布/生产环境在相同浏览器运行正常
• vite build后用vite preview运行无问题，仅vite开发服务器报错
• 注释所有Deck.gl代码可正常运行；只要引入Deck类（如GoogleMapsOverlay、TileLayer、GeoJsonLayer），即使未调用也会崩溃
• 延迟加载模块（如const { GoogleMapsOverlay } = await import('@deck.gl/google-maps');）能让项目渲染，但实际使用Deck模块时仍崩溃
• 同事使用完全相同的代码库无问题

解决方案 #

1. 调整Vite的依赖优化配置 #

Deck.gl依赖@luma.gl/core，Vite开发服务器的预构建逻辑可能导致WebGL模块初始化异常。尝试修改vite.config.js：

• 排除相关依赖的预构建：

export default defineConfig({
  optimizeDeps: {
    exclude: ['@deck.gl/core', '@luma.gl/core', '@deck.gl/google-maps']
  }
})

• 或者强制预构建这些依赖：

export default defineConfig({
  optimizeDeps: {
    include: ['@deck.gl/core', '@luma.gl/core']
  }
})

2. 临时禁用HMR排查冲突 #

热模块替换（HMR）可能干扰Deck.gl的WebGL上下文初始化，尝试关闭HMR：

export default defineConfig({
  server: {
    hmr: false
  }
})

若问题消失，说明HMR存在冲突，可尝试更新Vite到最新稳定版，或配置HMR排除规则：

export default defineConfig({
  server: {
    hmr: {
      exclude: ['**/@deck.gl/**', '**/@luma.gl/**']
    }
  }
})

3. 检查浏览器WebGL状态 #

• 重置浏览器设置（如Chrome的chrome://settings/reset），排除插件或自定义配置导致的WebGL异常
• 访问chrome://gpu/（Chrome）或safari://gpu/（Safari），确认WebGL 2.0已启用，无硬件加速禁用情况

4. 清理本地缓存 #

除node_modules外，清理以下缓存：

• 删除node_modules/.vite目录
• 在浏览器开发者工具中清空缓存并硬刷新（Ctrl+Shift+R）
• 运行yarn cache clean后重新安装依赖

5. 对齐Node.js版本 #

确保本地Node.js版本与同事、生产环境一致，不同版本可能导致依赖运行时差异。使用nvm切换版本：

nvm use [项目指定版本号]
yarn install

6. 强制更新Deck.gl及核心依赖 #

即使yarn.lock未修改，本地缓存可能存在异常，强制更新相关包：

yarn upgrade @deck.gl/core @deck.gl/google-maps @luma.gl/core --latest

测试通过后可提交更新后的yarn.lock到仓库。

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