React 17.0.1集成arcgis-js-api 4.18.1加载ESRI ArcGIS地图报错排查

实际控制台报错信息 #

[esri.widgets.Widget] widget-intl:locale-error esri.widgets.Attribution TypeError: t is not a constructor
[esri.widgets.Widget] widget-intl:locale-error esri.widgets.Zoom TypeError: t is not a constructor
index.js:1 [esri.widgets.Widget] widget-intl:locale-error esri.widgets.Popup TypeError: t is not a constructor
[esri.Basemap] #load() Failed to load basemap (title: 'Basemap', id: 'gray-vector') TypeError: t is not a constructor
workerFactory.js:5 Uncaught (in promise) TypeError: e is not a function
Uncaught (in promise) TypeError: Cannot read property 'zoomIn' of null

问题涉及的业务代码实现 #

import React, { useRef, useEffect } from 'react';
import { Card, CardBody, CardTitle } from 'reactstrap';
import ArcGISMap from '@arcgis/core/Map';
import MapView from '@arcgis/core/views/MapView';
import esriConfig from '@arcgis/core/config';

import '../../assets/css/map.css';

const SalesChartCard = () => {
  esriConfig.assetsPath = '/assets';

  const mapDiv = useRef(null);

  useEffect(() => {
    if (mapDiv.current) {
      const map = new ArcGISMap({
        basemap: 'gray-vector',
      });

      /* eslint-disable no-unused-vars */
      const view = new MapView({
        map,
        container: mapDiv.current,
        extent: {
          spatialReference: {
            wkid: 102100,
          },
          xmax: -13581772,
          xmin: -13584170,
          ymax: 4436367,
          ymin: 4435053,
        },
      });
      /* eslint-enable no-unused-vars */
    }
  }, []);

  return (
    <Card>
      <CardBody>
        <CardTitle>Map</CardTitle>
        <div className="mapDiv" ref={mapDiv} />
      </CardBody>
    </Card>
  );
};

export default SalesChartCard;

报错核心原因 #

• 版本导入路径完全不匹配：@arcgis/core 是 ArcGIS 4.19 版本之后才推出的模块化包入口，你使用的 4.18.1 版本根本不存在这个路径下的模块导出，所有从这个路径导入的类都是空值，初始化时自然会抛出“不是构造函数”的通用压缩报错。
• 静态资源路径配置无效：设置的 esriConfig.assetsPath = '/assets' 路径下没有部署 ArcGIS 运行必需的 worker 文件、组件语言包、样式与字体资源，直接导致 worker 加载失败、组件本地化功能报错。
• 缺少组件生命周期清理逻辑：React 17 开发模式下会重复执行两次 effect 逻辑，没有对已创建的 MapView 实例做销毁处理，容易出现容器重复绑定、实例空引用的报错。

落地解决步骤 #

• 先修正依赖与导入规则：把错误引入的 @arcgis/core 包卸载干净，安装和项目版本匹配的 arcgis-js-api@4.18.1，所有模块导入路径替换为 4.18 版本对应的 esri/xxx 格式；同时配置构建工具对 ArcGIS 模块的转译豁免规则，避免 Babel 过度转译破坏类的构造函数正常引用。
• 再修正资源路径：将 ArcGIS 运行需要的全量静态资源（worker、语言包、字体、样式文件）复制到项目 public 目录下的固定路径，把 esriConfig.assetsPath 指向这个真实存在的路径，不要指向空的静态目录。
• 最后补上组件清理逻辑：在 useEffect 里将 MapView 实例存在引用中，组件卸载时调用 view.destroy() 完成实例清理，增加重复初始化判断，避免开发模式下的双重执行逻辑引发空引用错误。

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