React useContext获取上下文时maps解构为undefined问题排查

算力阿峰

2026-9-3

报错根因

Cannot destructure property 'maps' of 'Object(...)(...)' as it is undefined 触发的核心原因是useContext(MapContext)的返回值为undefined，没有拿到Provider注入的值。结合你贴的代码，常见诱因有4个：

消费Context的组件不在MapContext.Provider的子树范围内：当前Provider仅包裹了<App />，如果在App外层、和Provider同层级的位置调用useContext，会直接拿到Context的默认值，而非Provider注入的值。
Context创建时未设置默认值：如果MapContext是通过createContext()无参创建的，组件脱离Provider子树时拿到的context值就是undefined，解构直接报错。
Context实例不匹配：如果消费组件导入的MapContext和Provider使用的MapContext不是同一个实例（比如路径配置错误、重复打包了多份Context文件），会导致消费端监听不到Provider的注入值。
地图实例初始化时机问题：如果导入的maps是异步初始化的，首次渲染时maps本身为undefined，也会触发解构报错。

是否需要搭配state使用

分两种场景判断：

如果maps是初始化后不会变更的静态OpenLayers实例，不需要触发消费组件重渲染，直接传值即可，无需搭配state。
如果maps实例后续会发生变更（比如切换地图实例、更新图层配置需要同步给所有消费组件），必须将maps存入state再传给Provider的value，否则值变更时消费组件不会自动重渲染拿最新值。

代码修正方案

首先修正Context创建逻辑，设置初始值避免undefined问题：

// MapContext.ts
import { createContext } from 'react';
// 传入初始null，配合后续消费端的校验逻辑
const MapContext = createContext<{ maps: any } | null>(null);
export default MapContext;

修正Provider层逻辑，需要动态更新地图实例时用state托管：

// mainapp.tsx
import { useState } from 'react';
import MapContext from 'openlayer/Map/MapContext';
import maps from 'openlayer/Map';

// 需要动态更新地图实例时打开下面这行
// const [mapInstance, setMapInstance] = useState(maps);

<Provider store={store}>
  <HelmetProvider>
    <React.StrictMode>
      <StylesProvider injectFirst>
        <MapContext.Provider value={{ maps: maps }}>
          <App />
        </MapContext.Provider>
      </StylesProvider>
    </React.StrictMode>
  </HelmetProvider>
</Provider>

修正消费组件逻辑，增加Context存在性校验，避免解构报错：

// 地图消费组件
import { useContext, useEffect } from 'react';
import MapContext from 'openlayer/Map/MapContext';

export default function MapContainer() {
  const ctx = useContext(MapContext);
  // 校验Context是否存在，提前抛出明确错误
  if (!ctx) throw new Error('MapContext只能在Provider包裹的子组件内使用');
  const { maps } = ctx;

  useEffect(() => {
    // 组件挂载阶段操作地图实例
    if (maps) {
      // 写你的地图渲染、图层配置逻辑
    }
  }, [maps]);

  return <div id="map" style={{ width: '100%', height: '100vh' }} />
}

可选替代方案

props透传：如果组件层级不深，直接把maps实例通过props逐层传递给需要的组件，逻辑更直观，也能避免Context带来的不必要重渲染。
全局状态库存放：如果项目已经接入Zustand/Redux等全局状态库，可以把maps实例存在全局状态中，配合选择器实现按需订阅，重渲染控制比原生Context更精细。
模块级单例：如果地图实例不需要响应式更新，可以直接把maps实例导出为模块单例，在需要的组件中直接导入使用，不需要走Context逻辑，适合逻辑简单的场景。

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