迁移不是把地图组件换个名字

ArcGIS JavaScript 应用迁到开放地图栈时，最容易犯的错误是把渲染器、服务访问、控件交互和业务查询打包成一次“大替换”。Honua JS SDK 的 README 提供了一个可审视的反例：它将自己定位为协议与应用集成层，而不是地图渲染器；MapLibre 是稳定二维渲染路径，Cesium 场景面仍是 beta，Kepler.gl 集成仍属 experimental。

这一区分很重要。地图能画出来，只能证明渲染器工作；并不能证明 FeatureServer、OGC API、STAC、WMS/WFS、鉴权、分页、取消请求和业务组件在迁移后仍保持原语义。迁移计划应分别验收数据服务、查询计划、地图呈现和交互组件。

一手事实：SDK 的稳定范围先于功能清单

README 将当前开发分支标为 beta 0.1.10-beta.0，并说明有 22 个 stable tier 入口、26 个 1.0 前可变化的 experimental subpaths，以及 18 个注明移除版本的 compatibility subpaths。它还明确提醒：开发分支的版本基线不能当作已发布 npm 行为的承诺，应以带标签 release 文档为准。

这意味着团队不能因为 README 展示了某个 ArcGIS compatibility、离线或三维接口，就把它直接写进生产替换范围。先固定实际安装版本和公开 API surface，再对每个使用点标记为 stable、experimental、deprecated 或没有等价物；只有前两类中的 stable 项才应进入默认上线清单。

协议查询要有计划，也要有失败语义

SDK 列出 Esri GeoServices、OGC API Features/Tiles/Maps/Processes、STAC、WMS、WMTS、WFS 2.0 与 OData v4 的 typed clients。其示例顺序是 connect、inspect、explain、query、mount：连接公共 FeatureServer 后，先检查服务，再产出可解释的查询计划，随后执行并挂载到 MapLibre。README 说明 result 保留有界执行证据，plan 解释被接受的查询；所有操作接受 AbortSignal，离开 await using 作用域会释放地图和连接。

真正值得迁移团队采用的不是 API 名称，而是这条顺序。先让服务和能力显式可见，再让地图消费一个有边界的查询结果。对于多个数据源的服务根目录，README 要求明确 sourceId，内核不会静默选择第一个公布的 source；inspect 默认读取连接时建立的 immutable snapshot，只有 refresh 才重验。这样可以防止服务目录变化后，应用悄悄改读另一个图层。

更关键的是失败语义：README 说明不支持的能力抛出 HonuaCapabilityNotSupportedError，而不是把不支持伪装为空结果。生产迁移也应保留这个原则：能力缺失、无数据、权限拒绝、超时和用户取消必须是不同状态。

组件替代与渲染器替代必须拆开

README 提到 ArcGIS classic widgets 在 JS SDK 5.0 已弃用，6.0 起会开始移除，并给出最早 2027 年第一季度的时间提示。这可以成为代码盘点的触发器，而不是仓促改写的理由。先扫描哪些页面真的构造了这些 widget，再分别决定：可自动迁移、需要人工改造、保留 ArcGIS 依赖，还是没有开放栈等价物。

对于二维业务地图，MapLibre 可以负责绘制；服务请求、字段解释、筛选、编辑、地理编码、路由和组件交互仍是独立契约。对于 SceneView 级三维能力，README 也坦承没有 3D parity，建议直接使用 CesiumJS 或继续保留 ArcGIS Maps SDK 的相应部分。把这些限制公开，反而比“全量兼容”更适合作为架构决策依据。

最小迁移验收路径

  1. 导出当前页面的服务、widget、图层、查询、权限和浏览器依赖清单。
  2. 用固定公开或脱敏 FeatureServer/OGC endpoint 复现 connect→inspect→explain→query，保存服务元数据、sourceId、计划、返回数和取消结果。
  3. 在 MapLibre 中比较同一范围、过滤、符号、点击与分页下的要素 ID、字段、坐标和视觉顺序。
  4. 对不支持的协议能力，断言得到明确错误，不能把错误页、空数组或超时当成无结果。
  5. 对每个旧 widget 记录替代方案、可用版本、人工复核点和回滚路径；没有等价物的功能保留原 SDK 或重做交互需求。
  6. 将浏览器、Node、MapLibre 与 SDK 版本锁入构建记录。README 的运行时表给出 Node.js >=20.19 和可选 maplibre-gl ^6.4.1；其中 6.4.1 是其标明的安全下限。

风险边界

Honua README 是一个 beta SDK 的项目说明，不是对所有 ArcGIS 应用、私有服务、定制 widget 或三维场景的兼容保证。开发分支的示例也不能替代已发布版本和项目自身的安全测试。特别是身份认证、私有端点、编辑事务、离线同步、性能与三维渲染，均须以真实部署条件单独验证。

结论

开放地图栈迁移的目标不应是“页面换成 MapLibre”，而是让每个服务访问、查询计划、组件替代和渲染能力都有明确边界。先拆开再验收，才能避免把协议缺失或组件差异伪装成一张看似正常的地图。

关键词：GIS 是地理信息系统；WebGIS 迁移应区分服务客户端和渲染器；多源服务必须显式选择图层；beta 能力不应直接进入生产默认路径。

参考资料