摘要：本文详解 SuperMap iServer REST 地图服务的加载原理，并分别给出OpenLayers（配合 iClient for OpenLayers） 和Leaflet（配合 iClient for Leaflet） 的完整可运行示例，附带坐标系匹配、跨域等常见坑位说明。
一、SuperMap iServer REST 地图服务简述
SuperMap iServer 发布地图后，会生成一个 REST 风格的服务地址，格式通常为：
http://ip:8090/iserver/services/地图服务名/rest/maps/地图名称例如超图官方示例：
https://iserver.supermap.io/iserver/services/map-world/rest/maps/World该接口支持返回地图元信息（JSON），以及按缩放级别请求栅格瓦片（ugcImage / tileImage）。
前端 GIS 库（OpenLayers / Leaflet）并不直接"原生"理解 SuperMap REST 瓦片组织方式，推荐使用超图官方封装的 iClient 扩展包（iClient for OpenLayers / iClient for Leaflet），它们内部完成了：
请求地图元信息获取 bounds、resolutions、tileSize
按 SuperMap REST 瓦片 URL 模板拼装请求
坐标系（EPSG:4326 / EPSG:3857 / EPSG:4490）适配与重投影
二、OpenLayers 加载 SuperMap iServer REST 图层
2.1 引入资源
<!-- OpenLayers --> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v7.4.0/ol.css" /> <script src="https://cdn.jsdelivr.net/npm/ol@v7.4.0/dist/ol.js"></script> <!-- SuperMap iClient for OpenLayers --> <script src="https://iclient.supermap.io/dist/ol/iclient-ol.min.js"></script>💡 若使用 Vue / React，可通过
npm install @supermap/iclient-openlayers引入TileSuperMapRest。
2.2 完整示例代码（EPSG:4326）
<div id="map" style="width:100%;height:500px"></div> <script> var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World"; var map = new ol.Map({ target: 'map', view: new ol.View({ center: [0, 0], zoom: 2, projection: 'EPSG:4326' }) }); var layer = new ol.layer.Tile({ source: new ol.source.TileSuperMapRest({ url: url, wrapX: true }), projection: 'EPSG:4326' }); map.addLayer(layer); </script>2.3 EPSG:3857 场景（常见 Web 墨卡托）
var layer = new ol.layer.Tile({ source: new ol.source.TileSuperMapRest({ url: "https://iserver.supermap.io/iserver/services/map-china400/rest/maps/China", wrapX: true }) }); var map = new ol.Map({ target: 'map', layers: [layer], view: new ol.View({ center: ol.proj.fromLonLat([116.4, 39.9]), zoom: 5, projection: 'EPSG:3857' }) });⚠️ 若服务本身是 EPSG:4326 而 View 用 EPSG:3857，OpenLayers 会自动做 raster reprojection，但建议服务投影与 View 投影一致以获得最佳性能和清晰度。
三、Leaflet 加载 SuperMap iServer REST 图层
3.1 引入资源
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" /> <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script> <!-- SuperMap iClient for Leaflet --> <script src="https://iclient.supermap.io/dist/leaflet/iclient-leaflet.min.js"></script>npm 方式：
npm install @supermap/iclient-leaflet，然后import { tiledMapLayer } from '@supermap/iclient-leaflet'。
3.2 完整示例代码（EPSG:4326）
<div id="map" style="width:100%;height:500px"></div> <script> var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World"; var map = L.map('map', { crs: L.CRS.EPSG4326, center: [0, 0], zoom: 1, maxZoom: 18 }); L.supermap.tiledMapLayer(url, { noWrap: false // 允许横向循环 }).addTo(map); </script>3.3 说明
L.CRS.EPSG4326：Leaflet 默认是EPSG:3857，加载超图 4326 服务必须显式指定 CRS，否则瓦片位置偏移。noWrap: false：全球数据建议开启横向平铺。
四、关键原理解析
要点 | 说明 |
|---|---|
REST 瓦片请求 | iClient 先 GET 地图元信息 JSON → 解析 |
坐标系适配 | 源投影取自服务元信息，View/Map 投影由前端指定，OpenLayers 可做自动 reproject；Leaflet 需手动配 |
wrapX | 全球经纬度服务建议 |
跨域(CORS) | iServer 需在「服务管理器 → 允许跨域」开启，否则浏览器拦截瓦片请求 |
分辨率数组 | 若用原生 OL |
五、常见问题排查
地图空白 / 404：检查 REST URL 是否以
/rest/maps/地图名结尾，不要少级或多加后缀。瓦片模糊或层级不对：EPSG:4326 服务被放到 EPSG:3857 View 中触发重投影，或 resolution 数组不匹配。
CORS 报错：iServer → 服务属性 → 跨域设置 → 允许 Origin
*（开发环境）。Leaflet 偏移：忘记设
crs: L.CRS.EPSG4326。
六、小结
✅推荐做法：使用
@supermap/iclient-openlayers的TileSuperMapRest和@supermap/iclient-leaflet的tiledMapLayer，省去手动拼瓦片模板和 resolution。✅ 注意坐标系一致，Leaflet 必须显式声明 CRS。
✅ iServer 开启 CORS，保证瓦片正常拉取。
如有 iServer WMTS / 矢量瓦片(MVT) / 动态图层(UTFGrid) 加载需求，可在评论区交流 👇
