Experience Builder 自定义应用的升级风险，常不在首个构建报错，而在构建通过后才出现：内网机器取不到依赖，旧 Popup 写法失效，帮助链接跳到不可访问的公网，或某个业务地图在组件更新后无法交互。ArcGIS Experience Builder Developer Edition 1.21 把依赖安装方式、离线资源、帮助链接和组件迁移同时带到台前，适合把升级改造成一次可回退的 WebGIS 变更。

研究的九项固定口径

  1. ArcGIS Experience Builder Developer Edition 1.21 已提供 2026 年 6 月 ArcGIS Online 更新中的多语言应用、QuickCapture 和 Image Change Detection widgets 等能力。

  2. 从 Developer Edition 1.21 起，pnpm 成为安装依赖的必需工具。

  3. 该版本建议使用 pnpm 11 与 Node.js 24。

  4. 1.21 的下载页面为受限网络或无网络环境提供 pnpm offline store。

  5. pnpm 只用于 server 和 client 文件夹中 node modules 与其他依赖的安装，启动服务仍使用 npm start。

  6. 开源 arcgis-exb-widget-dev coding skill 可通过自然语言提示协助创建、更新和现代化 Experience Builder widgets。

  7. 该 coding skill 会在需求不完整时收集 widget 能力、数据源要求和 widget 通信等信息，并且项目明确说明该 skill 不受支持。

  8. 1.21 支持在 setting.json 设置 customDocumentationBaseURL，将 Builder 帮助链接指向内部、离线、本地化或自定义 widget 文档。

  9. 升级前需要重点检查 pnpm 依赖安装、widgets 到 web components 的迁移（包括 Popup widget）以及 JavaScript Maps SDK 更新。

核心机制：把构建依赖和运行服务分开核对

1.21 最容易被误读成“把 npm 换成 pnpm”。官方说明区分得更细：pnpm 管理 server 与 client 目录的 node modules 和其他依赖，但服务仍通过 npm start 启动。团队应把安装命令、锁文件、Node 版本和启动命令分别写进运行手册，不能以一次本机成功安装替代环境验收。

最小的可回退单元是一份锁定的源代码、一份对应的 pnpm 依赖快照、一份 Node 运行时记录和一个可启动的旧版制品。先在隔离环境用干净工作目录安装并构建，再启动服务加载同一批地图和数据源；失败时恢复旧制品，而不是在生产机上临时改包版本。

GIS 场景：隔离网络与内部知识入口

许多政企 WebGIS 部署在受限网络。1.21 提供 pnpm offline store，正好可用来验证依赖是否真的能在断网环境完成安装。将 store 当作发布物管理：记录其对应的代码提交、pnpm 和 Node 版本，离线构建前校验校验和，构建后保留日志。它解决的是依赖可得性，不替代内部镜像、漏洞扫描或许可证审核。

Builder 的帮助链接也属于运行体验。customDocumentationBaseURL 可把设置面板的帮助导向内部文档、离线副本、本地化说明或自定义 widget 页面。部署前用普通编辑者账号逐个打开地图、数据、Widget 配置中的关键帮助入口，确认链接不泄露到不可访问的公网，也不指向已废弃版本。

技术路径：先迁移组件，再让 AI 辅助加速

官方将 widgets 到 web components 的迁移、Popup widget 和 JavaScript Maps SDK 更新列为 breaking changes 的重点。先建立一个组件清单：自定义 widget 名称、入口、用到的 Maps SDK API、Popup 交互、数据源、消息通信和代表性应用。为每项标记“未动、已迁移、待验证、已回退”，比把所有应用一次升级更容易定位问题。

arcgis-exb-widget-dev coding skill 可以用自然语言帮助创建或现代化 widget，也能在需求不全时询问能力、数据源和 widget 通信。它适合生成候选改动、补全迁移清单和提出测试点；由于官方明确其不受支持，任何生成代码都必须经过代码评审、类型/构建检查和真实地图回归，不能直接进入生产分支。

风险与检查清单

  1. 在干净环境固定 Node.js 24、pnpm 11、代码提交和锁文件，记录安装与构建日志。
  2. 断网或隔离网络中使用 pnpm offline store 重跑安装，确认没有未声明的外网依赖。
  3. 保持 npm start 的启动路径，分别验证 server、client、反向代理和登录入口。
  4. 逐项迁移并测试 Popup 与其他 widgets 到 web components 的改动，覆盖共享、筛选、查询和编辑等关键交互。
  5. 用至少一张生产代表性 Web Map、一个受保护数据源和一个移动端布局做冒烟测试。
  6. 设置 customDocumentationBaseURL 后，以普通编辑者身份检查内部帮助、离线帮助和自定义组件说明。
  7. 将 AI 辅助产生的改动单独提交，保留人工审查、测试结果和可快速恢复的旧版构建。

结论

Experience Builder 1.21 的升级验收不应止于依赖装好。把 pnpm 与 npm start 的职责拆开，验证离线 store 和内部帮助入口，再以组件清单驱动 Popup、Maps SDK 与业务地图回归，才能让自定义 WebGIS 在升级后仍可构建、可运行、可支持并可回退。

资料来源