地图 API 统一入口

地图瓦片与样式资源
一个域名就够了

MapCDN 为 OpenStreetMap、Mapbox 与 MapLibre 相关资源提供反向代理。官网是 mapcdn.io，API 使用 map.bluecdn.com，前端只需要替换 URL 即可接入。

OSM 瓦片
Mapbox Style
Glyphs 字体
Sprites 图标
Leaflet / MapLibre
CORS 开放

1快速开始

把地图组件的瓦片地址替换成 map.bluecdn.com。推荐优先使用这个 API 域名，官网 mapcdn.io 用于文档与说明。

https://map.bluecdn.com/osm/{z}/{x}/{y}.png
统一入口

所有地图资源都走 map.bluecdn.com，用路径区分瓦片、样式、字体和 sprites。

map.bluecdn.com/osm/...
直接跨域调用

响应包含 CORS 头，Leaflet、MapLibre GL JS、Mapbox GL JS 可以在浏览器端直接请求。

Access-Control-Allow-Origin: *
服务端注入 Token

Mapbox token 由代理服务端注入，页面中的公开 URL 不需要携带 access_token。

/mapbox/styles/mapbox/streets-v12

2主题预览

常见地图图片主题与样式入口。预览图是轻量静态图，用于展示视觉方向；实际地图由 map.bluecdn.com 按路径反代。

上海人民广场 OSM 标准地图真实预览

OSM 标准

Raster

通用街道底图，适合后台选点、门店地图、城市浏览。

https://map.bluecdn.com/raster/osm/{z}/{x}/{y}.png
上海人民广场 CARTO Voyager 地图真实预览

Voyager

Raster

CARTO Voyager 街道底图，适合 POI、路线和城市业务地图。

https://map.bluecdn.com/raster/voyager/{z}/{x}/{y}.png
上海人民广场 CARTO Light 地图真实预览

Light

Raster

浅色、低干扰底图，适合数据可视化和业务覆盖层。

https://map.bluecdn.com/raster/light/{z}/{x}/{y}.png
上海人民广场 CARTO Dark 地图真实预览

Dark

Raster

深色视觉，适合大屏、监控、夜间模式和高亮轨迹。

https://map.bluecdn.com/raster/dark/{z}/{x}/{y}.png
上海人民广场 OpenTopoMap 地形地图真实预览

Topo

Raster

OpenTopoMap 地形底图，适合户外、路线和区域展示。

https://map.bluecdn.com/raster/topo/{z}/{x}/{y}.png
上海人民广场 Esri World Imagery 卫星地图真实预览

Satellite

Raster

影像底图方向，适合地块、园区、实景参照和空间核验。

https://map.bluecdn.com/raster/satellite/{z}/{x}/{y}.jpg
以上预览图均为真实瓦片生成，固定坐标为上海人民广场附近 31.2304, 121.4737，缩放级别 13。

3引用方式

常见前端地图库的最小接入示例。生产页面请保留地图数据来源 attribution。

Leaflet 使用 OSM 栅格瓦片

const map = L.map("map").setView([31.2304, 121.4737], 11);

L.tileLayer("https://map.bluecdn.com/osm/{z}/{x}/{y}.png", {
  maxZoom: 19,
  attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

MapLibre GL JS 使用 Mapbox Style

const map = new maplibregl.Map({
  container: "map",
  style: "https://map.bluecdn.com/mapbox/styles/mapbox/streets-v12",
  center: [121.4737, 31.2304],
  zoom: 10
});

Mapbox GL JS 使用代理 Style

mapboxgl.accessToken = "not-required-in-public-url";

const map = new mapboxgl.Map({
  container: "map",
  style: "https://map.bluecdn.com/mapbox/styles/mapbox/light-v11",
  center: [116.3974, 39.9093],
  zoom: 10
});

4API 路径

当前版本先覆盖地图页面最常用的资源类型，后续可以扩展卫星图、地形、PMTiles 或自托管矢量瓦片。

资源路径说明
OSM raster tiles /osm/{z}/{x}/{y}.png 代理 OpenStreetMap 标准栅格瓦片，适合 Leaflet 与轻量地图展示。
Raster themes /raster/{theme}/{z}/{x}/{y}.{png,jpg} 真实栅格主题入口：osm、light、dark、voyager、topo、satellite。
Mapbox style /mapbox/styles/{owner}/{style_id} 返回 Mapbox Style JSON，例如 mapbox/streets-v12。
Mapbox sprites /mapbox/styles/{owner}/{style_id}/sprite[@2x].{json,png} 样式图标资源，支持普通和 2x 版本。
Mapbox glyphs /mapbox/fonts/{owner}/{fontstack}/{range}.pbf 字体 PBF，例如 Open%20Sans%20Regular/0-255.pbf。
Mapbox tiles /mapbox/tiles/{tileset}/{z}/{x}/{y}.{mvt,pbf,png,jpg,webp} 代理指定 tileset 的矢量或栅格瓦片。

5使用说明

MapCDN 是地图资源反代，不是完整地图应用。高流量生产业务建议准备自托管瓦片或商业地图源作为长期方案。

保留署名

使用第三方底图时，请按来源保留 OpenStreetMap、CARTO、OpenTopoMap、Esri 等 attribution。

遵守缓存

服务会透传上游缓存头；客户端不要对瓦片做无意义的强制刷新。

合理流量

公共瓦片源不适合大规模离线下载。高流量场景建议使用自托管或商业地图源。

OpenStreetMap 官方不鼓励滥用公共瓦片服务。MapCDN 默认设置可联系的 User-Agent，并保留上游缓存策略；生产大流量业务建议迁移到自建瓦片源、Mapbox、MapTiler、OpenMapTiles 或 PMTiles。