SuperMap iClient for Leaflet 常见错误与解决

wowwwai GIS研习社 · 工具流程与项目排障

SuperMap iClient for Leaflet 常见报错主要集中在库引入与打包失败、地图坐标系未手动设置导致偏移、带裁剪参数时瓦片请求过长无法出图，以及部分第三方底图拼接异常这几类。核对 Leaflet 版本兼容范围、正确指定 map 的 crs、必要时改写 TileLayer 请求方式，就能解决绝大多数问题。截至 2026 年产品线，Leaflet 兼容 v1.0.3～v1.9.4，npm 包请使用 @supermapgis/iclient-leaflet（自 11.2.0 起已从旧包名迁移）。

引入与打包时报错怎么排查

最先检查的是引入方式和依赖版本。CDN 方式需同时引入 Leaflet 的 CSS/JS 与 iclient-leaflet 的 CSS/JS；只引 JS 不引 CSS 会出现控件样式错乱或图层异常。模块化项目用 npm 安装时，11.2.0 及以后请安装 @supermapgis/iclient-leaflet，旧版才是 @supermap/iclient-leaflet，包名写错会直接找不到模块。

按需引入时若出现 “does not match the corresponding path on disk ‘Logger.js’” 一类路径报错，通常是 babel-plugin-import 配置位置不对：请把配置写在 .babelrc 里（libraryName 设为 “@supermapgis/iclient-leaflet”），写在 babel.config.js 往往无效。打包还需配合 babel-loader 与 @babel/preset-env 转换 ES6。

1. 确认 Leaflet 版本落在当前产品兼容区间（2026 产品为 1.0.3～1.9.4），并同时引入双方 CSS。
2. npm 安装最新包：npm install @supermapgis/iclient-leaflet，旧项目升级时同步改包名与 import 路径。
3. 按需引入时安装 @supermapgis/babel-plugin-import，配置放进 .babelrc 后重新编译。
4. 仍报错时到 GitHub Releases 查看最新版本与更新说明，核对本地版本是否过旧或依赖冲突。

验收标准：控制台无模块解析错误，地图容器能正常创建，无样式丢失。发布服务端地图时若用到桌面端，可先确认 SuperMap iDesktop 下载与试用许可申请 流程，保证 iServer 服务可访问。

地图出图偏移或查询位置不准怎么修

iClient for Leaflet 不会自动读取 iServer 服务的坐标系，必须在创建 map 时手动指定 crs。常用世界地图示例要设 crs: L.CRS.EPSG4326，再用 L.supermap.tiledMapLayer(url).addTo(map)。若服务是自定义投影或平面坐标，需用 L.Proj.CRS（或对应命名空间）定义 origin、scales/resolutions、bounds 等参数，非标准投影先用 proj4js.defs 注册。

Leaflet 自身绘制与 marker 使用经纬度。非 EPSG:4326 地图上，客户端绘制结果需经 CRS.project 转成投影坐标再参与查询/分析，服务返回结果再 unproject 回经纬度显示，否则会出现明显偏移。自定义参数可参考 epsg.io 的 proj4 定义，并仔细核对起算点与分辨率。

• 默认支持：EPSG:4326、EPSG:3857、平面无投影。
• 自定义 CRS 时至少提供 origin + scales（或 scaleDenominators/resolutions）+ bounds 中的必要项。
• 查询、量算、标绘前后务必做坐标转换，避免“图上看着对、属性位置错”。

数据导入或桌面端坐标参数本身有问题时，地图服务也会带着错误信息下来，可结合 SuperMap 导入数据乱码与坐标转换参数设置 先把源数据 CRS 理顺再发布。

瓦片请求体过长无法出图如何处理

使用 clipRegion 等复杂过滤或裁剪参数时，部分环境会把参数拼进 GET 的 URL，导致请求体（实际是查询串）过长，服务端拒绝或浏览器拦截，表现为空白瓦片或出图失败。官方技术支持给出的可行做法是重写 Leaflet TileLayer 的取瓦片逻辑，改为 POST，把参数放进 body，并在 URI 后附加 _method=GET 以兼容服务端习惯。

1. 定位到使用了 clipRegion 或其他大参数的 TiledMapLayer / 自定义 TileLayer。
2. 重写 getTile（或对应取图方法），将请求改为 POST，参数放入请求体。
3. URI 保留必要路径并加上 _method=GET，保证 iServer 仍按原接口处理。
4. 清缓存后刷新，检查网络面板中瓦片请求是否变为 POST 且状态 200、图片正常返回。

验收标准：带裁剪条件的图层能稳定出图，控制台无 414/431 或请求过长类错误。若服务本身由桌面端发布，确认发布参数与坐标系无误后再测客户端。

百度瓦片与版本兼容要注意什么

使用 baiduTileLayer 且 noWrap 设为 false 时，部分缩放级别（如 3、4）世界地图可能出现缝隙、不连续。这是因为百度瓦片金字塔的起算点与分辨率计算方式和标准 Web 墨卡托不同，边缘瓦片自身填充不满，属于已知限制，暂时难以做到完全无缝拼接。业务上若必须无缝，可考虑改用标准 3857/4326 底图或接受特定级别的视觉缝隙。

版本与环境方面，请对照下表做快速核对（以 2026 产品概览为准，更早产品兼容范围更窄）：

项目	要求说明
Leaflet 版本	2026 产品兼容 v1.0.3～v1.9.4
npm 包名	11.2.0 起为 @supermapgis/iclient-leaflet；更早用 @supermap/iclient-leaflet
当前常见版本	12.1.x 系列（如 12.1.3 等，以 GitHub Release 为准）
浏览器	Desktop Chrome 26+、Firefox 23+、Safari 5+ 等；IE8 需额外 es5-shim（Leaflet 1.2+ 已不建议 IE8）
必引样式	Leaflet CSS + iclient-leaflet CSS

第三方可选依赖（ECharts、MapV、proj4js、Turf 等）版本以产品概览中的插件表为准，避免自行混用过新或过旧版本导致冲突。

常见问题

为什么设置了服务地址还是不出图？

先看浏览器网络面板瓦片请求是否 200、是否跨域被拦；再确认 map 已正确设置 crs，且同时引入了 Leaflet 与 iClient 的 CSS。CRS 错误时常常“请求成功但位置全错或空白”。

升级后 import 全部报错怎么办？

检查是否仍在使用旧包名 @supermap/iclient-leaflet；11.2.0 之后必须改为 @supermapgis/iclient-leaflet，并同步更新 babel-plugin-import 的 libraryName，然后清缓存重新安装依赖。

自定义投影下标绘位置总对不上？

Leaflet 绘制得到的是经纬度，必须用当前 CRS 的 project 转成服务投影坐标再查询或提交，结果再 unproject 回来；同时确认 origin、resolutions、bounds 与服务端完全一致。

百度底图中间有缝是 bug 吗？

在 noWrap=false 且部分低级别下属于已知现象，由百度瓦片组织方式决定，官方曾说明暂时无法实现完全无缝，可换标准坐标系底图或接受该级别视觉效果。

排查顺序建议固定为：先确认包名与 Leaflet 版本 → 再核对 map.crs 与投影参数 → 最后处理请求过长或第三方底图特殊行为。版本信息以 GitHub Releases 为准及时更新；涉及源数据坐标与桌面端发布时，可同步参考本站 坐标转换参数设置说明 与 iDesktop 下载与许可申请，从服务源头减少客户端报错。