Appearance
SDK 指南
GeoBridge JS SDK 让网页和 Node 程序只用「平台地址 + API Key（或公开服务）」就能把平台的地图服务放进 MapLibre 地图，并做属性与空间查询。
- 零运行时依赖，目标 ES2020，只用浏览器与 Node 18+ 都有的
fetch、URL、AbortController。 - 不打包 MapLibre，只按 MapLibre 的公开接口生成样式与图层，maplibre-gl 5 与 6 都可以使用。OpenLayers 等其他库可以用 SDK 生成的地址，见 OpenLayers 对照。
- 当前版本 0.1.0。完整的方法列表见 API 参考。
引入方式
从在线系统下载（推荐）
在线系统自带 SDK 的浏览器版本（UMD）：https://map-demo.geobridge.cn/geobridge-mapserver/sandbox/vendor/geobridge-sdk.umd.js。把它下载到自己网站的静态目录，用 <script> 引入，全局变量名为 GeoBridge：
html
<script src="./vendor/geobridge-sdk.umd.js"></script>
<script>
const client = new GeoBridge.GeoBridgeClient({ baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver', apiKey: 'gb_xxx…' })
</script>同一目录下的 maplibre-gl/ 是 MapLibre GL JS 的浏览器版本，可以一并下载使用。请不要在生产页面中直接引用在线系统上的脚本地址，下载到自己的站点更稳定。
离线包与在线沙箱
- 本地部署的平台同样在
/sandbox/vendor/geobridge-sdk.umd.js提供这个文件。 - 在线沙箱的「下载」按钮得到的 HTML 通过
./vendor/…引用 SDK 与 MapLibre，见在线沙箱。
许可与 npm
SDK 以 MIT 许可开源，可以自由用于商业项目、修改和再分发，只需保留许可声明。SDK 暂未发布到 npm。在使用打包工具的项目里，可以把 UMD 文件放进项目目录后按路径导入，或继续用 <script> 引入并使用全局变量 GeoBridge。
快速开始
js
// 页面已用 <script> 引入 SDK（全局 GeoBridge）与 MapLibre（maplibregl）
const client = new GeoBridge.GeoBridgeClient({
baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver', // 平台根地址；不带查询串与片段
apiKey: 'gb_xxx…', // 只访问公开服务时可以不写
})
const path = 'city-roads' // 服务路径：服务名，或 目录/服务名
const map = new maplibregl.Map({
container: 'map',
style: await client.maplibre.serviceStyle(path), // 矢量瓦片服务的样式
transformRequest: client.transformRequest, // 给发往平台的请求带上 Key
})
const bounds = await client.services.extent(path) // 服务的数据范围（经纬度）
if (bounds) map.fitBounds(bounds, { padding: 20 })serviceStyle()取回服务的 MapLibre 样式，其中的数据源、字体、雪碧图都指向平台，可以直接作为地图样式。transformRequest: client.transformRequest必须传：MapLibre 加载瓦片、字体、雪碧图时，由它给平台地址加上 Key。不传时「API Key」级别的服务瓦片全部 401。- 在已有的地图上叠加服务用
client.maplibre.addVectorTileService()或addRasterService()，见 API 参考。 - 一个完整的 HTML 页面（含 MapLibre 的引入方式）见快速开始（在线）。
客户端选项
new GeoBridgeClient(options)：
| 选项 | 默认 | 说明 |
|---|---|---|
baseUrl | 必填 | 平台根地址，http 或 https，含上下文路径（如 https://gis.example.com/geobridge）；不能带用户信息、查询串与片段，尾部的 / 会去掉 |
apiKey | 无 | gb_ 开头的 API Key；不给则匿名，只能访问公开服务 |
keyTransport | 'header' | Key 的传递方式：'header'（请求头）或 'query'（查询参数），见下文 |
platformUrls | 无 | 其他也属于本平台的地址前缀，见下文 |
timeoutMs | 30000 | 单次尝试的超时毫秒数 |
retries | 2 | GET 请求的重试次数 |
fetch | 全局 fetch | 自定义 fetch 实现，便于测试或在特殊运行环境中使用 |
选项不合法时构造函数抛 TypeError。
API Key 的传递
keyTransport | 做法 | 何时用 |
|---|---|---|
'header'（默认） | 请求头 X-GeoBridge-Token | 一般情况：Key 不出现在地址里，不会进入访问日志与浏览器历史 |
'query' | 查询参数 token | 跨域、瓦片量大、对加载速度敏感的页面：带自定义请求头的跨域请求，浏览器会对每个不同的地址先发一次预检，查询参数没有这个开销；代价是 Key 出现在地址里 |
Key 只发给 baseUrl 之下的地址。 SDK 先把地址规范化（消解 .. 等路径段），再判断它是否等于 baseUrl（或 platformUrls 中的某一项）或以「前缀/」开头；其他主机的地址（如第三方底图）原样放行，绝不附带 Key。client.request() 遇到不属于平台的绝对地址直接抛 FOREIGN_URL。
不能加请求头的库（<img>、OpenLayers 的 XYZ 与 WMS 源等）用 client.withKey(url) 给平台地址补上 token：
js
const source = new ol.source.XYZ({ url: client.withKey(client.services.tileUrl('city-roads')) })platformUrls：平台有多个地址时
矢量瓦片服务的样式、WMTS 能力文档里的地址，是平台按自己配置的对外地址拼出来的。如果你填的 baseUrl 与它字面上不同（localhost 与 127.0.0.1、内网与外网域名、经反向代理的端口），这些地址就不被视为平台地址：'header' 模式下不会加 Key，「API Key」级别服务的瓦片全部 401。处理办法二选一：
- 把
baseUrl写成与平台对外地址一致； - 把平台的对外地址也写进
platformUrls。
serviceStyle() 与 addVectorTileService() 在 'header' 模式且带 Key 时，发现样式中有不属于平台的数据源、字体或雪碧图地址，会在控制台警告一次（只含地址来源，不含 Key）。'query' 模式下平台会自行改写样式中的地址并带上 token，不需要处理。
WARNING
platformUrls 中的地址同样会收到 Key，只填你信任的平台地址。
Key 不会被泄露到日志
- Key 保存在私有字段中，不出现在
String(client)、JSON.stringify(client)中。 - 错误的
message与url中出现的 Key 已替换为***，可以放心打印或上报。 - 在网页里使用的 Key 对访问者是可见的（开发者工具中能看到请求），请给它配置来源域名白名单，见 API Key 与来源白名单。
重试、超时与取消
- 重试：只重试 GET，且只在网络错误与 HTTP 429、502、503、504 时重试，默认 2 次。等待时间从 300 毫秒起每次翻倍；响应带
Retry-After时取两者中较大的，单次等待不超过 5 秒。其他 4xx 与 POST 请求不重试。 - 超时：
timeoutMs对每次尝试单独计时，超时抛TIMEOUT。 - 取消：
client.request()接受signal（AbortController的信号），中止后抛ABORTED。 - 重定向：SDK 不跟随重定向（避免请求头里的 Key 被带到其他主机），遇到 3xx 抛
REDIRECT。常见原因是http被重定向到https，请把baseUrl直接写成最终地址。
所有失败都抛 GeoBridgeError，错误码一览见 API 参考 与错误码。
在 Cesium 中使用
实验功能
三维服务（3D Tiles、点云、高斯泼溅、三维模型、网格地形、栅格地形）是实验功能，需要平台开启三维开关（GEOBRIDGE_FEATURE_3D=true，见功能开关）。开关关闭时三维服务的接口不存在，请求得到 404。
client.cesium 在 CesiumJS 中加载平台的三维服务。SDK 本身不包含 Cesium，也不依赖它：
- 自行引入 CesiumJS 1.146 或更高版本。 高斯泼溅以 3D Tiles 发布，使用 Cesium 1.146 起稳定支持的格式，更早的版本无法显示泼溅；其他三维服务同样按 1.146 验证。
- 把 Cesium 命名空间对象作为第一个参数传入。 用打包工具时为
import * as Cesium from 'cesium'得到的对象；用<script>引入 Cesium 的构建版本时为全局变量Cesium。 - Key 的传递与二维相同：SDK 用
client.cesium.resource()生成带 Key 的Cesium.Resource，子瓦片与地形瓦片的请求沿用同样的 Key，不需要另外设置。 - 平台的三维服务不需要 Cesium ion。若不使用 ion，创建
Viewer时请自行指定底图（或baseLayer: false），并关闭依赖 ion 的控件（如geocoder: false）。
js
// 页面已用 <script> 引入 CesiumJS（全局 Cesium）与 SDK（全局 GeoBridge）
const client = new GeoBridge.GeoBridgeClient({ baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver', apiKey: 'gb_xxx…' })
const viewer = new Cesium.Viewer('cesiumContainer', { baseLayer: false, geocoder: false, baseLayerPicker: false })
// 网格地形
viewer.terrainProvider = await client.cesium.terrainProvider(Cesium, 'terrain-mesh')
// 3D Tiles（含点云与高斯泼溅），加载后飞过去
const tileset = await client.cesium.addTileset(Cesium, viewer, 'city-3d', { flyTo: true })
// 点云按分类着色
const cloud = await client.cesium.addTileset(Cesium, viewer, 'pointcloud')
cloud.style = client.cesium.pointCloudStyle(Cesium, cloud, 'classification')
// 三维模型服务：glTF 按默认位置放置，泼溅按 3D Tiles 加载
const { skipped } = await client.cesium.addModels(Cesium, viewer, 'models')
skipped.forEach((s) => console.warn(s.name, s.message))栅格地形也可以在 MapLibre 中作为三维地形使用，见 maplibre.setRasterTerrain()。各方法的参数与返回值见 API 参考：client.cesium；三维服务的发布与预览见三维概览，可运行的示例见三维示例。
兼容性
- 浏览器：支持 ES2020 与
fetch的现代浏览器。 - Node：18 及以上（内置
fetch）；在 Node 中无需 MapLibre，可以只用services与query。 - MapLibre GL JS：5 与 6。注意 MapLibre GL JS 6 只提供模块脚本，页面要通过 http(s) 打开，不能用
file://。 addVectorTileService()、addRasterService()、setRasterTerrain()需要在地图load事件之后调用。- CesiumJS（
client.cesium，实验功能）：1.146 及以上。