如何让ArcGIS JavaScript SDK应用离线运行，避免调用js.arcgis.com

问题描述 #

我正在使用ArcGIS JavaScript SDK开发JavaScript应用，要求应用能在本地环境运行且无外部依赖。目前通过开发者工具发现应用频繁调用js.arcgis.com，且在node_modules的ArcGIS相关目录中发现该域名被硬编码。请问如何配置才能让SDK不发起对js.arcgis.com的请求？

现有配置文件及代码 #

package.json

{
  "engines": {
    "npm": ">=10.8.3 <=10.8.3",
    "node": ">=22.9.0 <=22.9.0"
},
  "name": "buildingmonitor",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
  "dev": "vite",
  "build": "tsc -b && vite build && npm run copyAssets",
  "lint": "eslint .",
  "preview": "vite preview --port 5173",
  "postinstall": "npm run copyAssets",
  "copyAssets": "shx mkdir -p ./public/assets && shx cp -r node_modules/@esri/calcite-components/dist/calcite/assets/* ./public/assets/",
  },
  "dependencies": {
    "@arcgis/map-components-react": "^4.31.6",
    "@esri/arcgis-rest-auth": "^3.7.0",
    "@esri/arcgis-rest-request": "^4.2.3",
    "@esri/calcite-components-react": "^2.13.2",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router": "^7.0.2"
  },
  "devDependencies": {
    "@eslint/js": "^9.15.0",
    "@types/node": "^22.10.2",
    "@types/react": "^18.3.12",
    "@types/react-dom": "^18.3.1",
    "@types/react-modal": "^3.16.3",
    "@vitejs/plugin-react": "^4.3.4",
    "eslint": "^9.16.0",
    "eslint-plugin-react": "^7.37.2",
    "eslint-plugin-react-hooks": "^5.0.0",
    "eslint-plugin-react-refresh": "^0.4.14",
    "globals": "^15.12.0",
    "shx": "^0.3.4",
    "typescript": "~5.6.2",
    "typescript-eslint": "^8.15.0",
    "vite": "^6.0.0"
  }
}

Map Widget代码

import "@arcgis/map-components/dist/components/arcgis-map";
import { ArcgisMap } from "@arcgis/map-components-react";
import { ArcgisMapCustomEvent } from "@arcgis/map-components/dist/types";

const MapWidget = () => {
  const handleMapReady = (event: ArcgisMapCustomEvent<void>) => {};

  return (
    <ArcgisMap
      onArcgisViewReadyChange={handleMapReady}
    />
  );
};

export default MapWidget;

解决方案 #

要彻底消除对js.arcgis.com的外部请求，需配置SDK使用本地资源部署模式，步骤如下：

1. 安装核心本地SDK包 #

当前仅使用了React组件封装包，缺少核心SDK的本地资源，需补充安装：

npm install @arcgis/core @arcgis/map-components

2. 配置Vite处理本地资源 #

在vite.config.ts中添加资源别名、路径配置，确保ArcGIS的静态资源能被正确打包和访问：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@arcgis/core': path.resolve(__dirname, 'node_modules/@arcgis/core')
    }
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: undefined
      }
    }
  },
  server: {
    fs: {
      allow: ['node_modules/@arcgis/core']
    }
  }
});

3. 修改组件代码，禁用CDN加载 #

通过esriConfig强制指定本地资源路径，同时替换默认的在线基础地图：

import { useEffect } from 'react';
import { ArcgisMap } from "@arcgis/map-components-react";
import { ArcgisMapCustomEvent } from "@arcgis/map-components/dist/types";
import esriConfig from '@arcgis/core/config';

const MapWidget = () => {
  useEffect(() => {
    // 配置SDK使用本地资源，完全禁用CDN
    esriConfig.urls.arcgis = "/assets/arcgis";
    esriConfig.loaderUrl = "/assets/arcgis/init.js";
    esriConfig.cdnUrl = "";
    // 加载本地calcite样式
    import("@esri/calcite-components/dist/calcite/calcite.css");
  }, []);

  const handleMapReady = (event: ArcgisMapCustomEvent<void>) => {};

  return (
    <ArcgisMap
      onArcgisViewReadyChange={handleMapReady}
      // 使用本地基础地图（需提前准备离线地图资源）
      mapProperties={{
        basemap: "gray-vector" // 若要完全离线，需替换为本地瓦片地图配置
      }}
    />
  );
};

export default MapWidget;

4. 更新postinstall脚本复制ArcGIS资源 #

在package.json的scripts中添加复制ArcGIS核心静态资源的命令，确保构建后资源可本地访问：

"scripts": {
  "dev": "vite",
  "build": "tsc -b && vite build && npm run copyAssets && npm run copyArcGISAssets",
  "lint": "eslint .",
  "preview": "vite preview --port 5173",
  "postinstall": "npm run copyAssets && npm run copyArcGISAssets",
  "copyAssets": "shx mkdir -p ./public/assets && shx cp -r node_modules/@esri/calcite-components/dist/calcite/assets/* ./public/assets/",
  "copyArcGISAssets": "shx mkdir -p ./public/assets/arcgis && shx cp -r node_modules/@arcgis/core/assets/* ./public/assets/arcgis"
}

5. 配置完全离线的基础地图（可选但关键） #

如果需要彻底无外部依赖，不能使用ArcGIS Online的基础地图服务，需：

• 准备本地瓦片地图资源（如使用ArcGIS Pro导出离线地图包）
• 将瓦片资源放置在public/assets/local-basemap目录下
• 修改mapProperties引用本地地图：

mapProperties={{
  basemap: {
    baseLayers: [{
      type: "tile",
      url: "/assets/local-basemap"
    }]
  }
}}

关键注意事项 #

• @arcgis/map-components-react默认会从CDN拉取核心SDK，必须通过esriConfig覆盖配置
• 所有ArcGIS静态资源（样式、字体、WebAssembly文件）都需复制到本地public目录
• 若保留ArcGIS Online的基础地图或服务，仍会产生外部请求，需全部替换为本地资源

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