常见问题

访问一个服务，为什么有时返回 401、有时返回 404？

为了不透露某个服务是否存在，匿名访问不存在的服务返回 401 UNAUTHORIZED，带了 Key 返回 401 TOKEN_INVALID，只有已登录的用户才会看到 404。所以匿名收到 UNAUTHORIZED 时，也可能是服务名或路径写错了，请先核对服务地址。

详见错误码。

把 API Key 写在网页里安全吗？

网页里使用的 Key 对访问者是可见的，打开浏览器的开发者工具就能看到。请为这类 Key 配置域名白名单，只把确实要对外的服务设为「API Key」级别，并定期轮换（新建一个、替换后撤销旧的）。Key 只能读取，不能编辑数据。

详见 API Key 与来源白名单。

设置了来源白名单，为什么还能被别的程序调用？

域名白名单检查的是浏览器发送的 Origin、Referer 请求头，只能约束浏览器，非浏览器程序可以随意伪造。要限制第三方服务器，请使用 IP 白名单。本地部署的平台放在反向代理之后时，需要代理正确传递客户端地址，否则 IP 白名单无法正确匹配。

详见 API Key 与来源白名单与 HTTPS 与反向代理。

矢量瓦片或切片不出图怎么办？

依次检查：

• 服务是否在运行：停止的服务返回 503。
• 切片地址的顺序：平台的切片地址是 tile/{z}/{y}/{x}，行号 {y} 在前，写成 {x}/{y} 会请求到错误的位置。
• Key 是否随瓦片请求发出：「API Key」级别的服务，MapLibre 要设置 transformRequest: client.transformRequest；样式里的地址与 baseUrl 不一致时 Key 不会附加，见 SDK 指南。
• 级别是否太低：数据量大的图层有最低输出级别，更低级别的瓦片中没有该图层（tiles.json 中图层的 minzoom）；小于约一个像素的要素在当前级别也不输出，放大后出现。
• 跨域：服务地址允许任何网页跨域读取；浏览器控制台出现跨域错误时，多半是地址写错（落到了不提供跨域的管理接口）或中间的代理改写了响应头。

详见 REST 服务与错误码。

数据改了，地图为什么没变？

经平台修改的数据（要素编辑、修改图层或样式、重新发布），平台的缓存会自动失效，但浏览器还会使用已缓存的瓦片，最长约 5 分钟；经过 CDN 时还要加上 CDN 的缓存时间。在平台之外直接修改数据库时，请在控制台服务详情点「清除瓦片缓存」。

详见缓存与性能。

在线沙箱里填了 Key，为什么被拒绝？

沙箱的预览出于安全考虑运行在隔离的环境中，请求不带可识别的来源域名，设置了域名白名单的 Key 在沙箱里一定会被拒绝（TOKEN_INVALID）。请在沙箱中使用没有域名白名单的 Key，或把代码下载为 HTML 放到白名单内的站点上运行。

详见在线沙箱。

服务发布了，为什么访问不到？

• 从图层或地图发布的服务需要手动启动，停止的服务返回 503。
• 新建的服务默认私有，只有登录的工作空间成员能访问；给外部使用请改为「公开」或「API Key」。

详见发布服务与访问级别。

为什么查询只返回 1000 条要素？怎样取全？

FeatureServer 查询单次返回的要素数受图层的最大要素数限制（未设置时为 1000）。结果被截断时响应带 exceededTransferLimit: true（GeoJSON 在顶层 properties 中），用 resultOffset、resultRecordCount 分页取下一页；用 JavaScript SDK 时 client.query.allFeatures() 会自动逐页取全。只需要数量时用 returnCountOnly，计数不受此限制。也可以为服务开启 WFS 并按 STARTINDEX 翻页，或开启 OGC API 并沿 next 链接翻页。

详见 REST 服务、WFS 分页与 OGC API Features。

client.services.list() 为什么返回 401？

服务目录不对匿名开放：不带 Key 且未登录时返回 TOKEN_REQUIRED。请在 GeoBridgeClient 中配置 apiKey。只想把地图定位到服务范围时，用 client.services.extent()，它匿名也能读取公开服务。

详见 API 参考。

SDK 报 REDIRECT 错误是什么原因？

平台地址发生了重定向，常见于 http 被重定向到 https。SDK 不跟随重定向（避免 Key 被带到其他主机），请把 baseUrl 直接写成最终地址。

详见 SDK 指南。

QGIS 能读到 OGC 服务的能力文档，但加载图层失败？

能力文档中的操作地址由平台的对外访问地址生成。本地部署时该地址不是客户端能访问的地址（如写成了内网 IP），GIS 软件后续的请求就会发到错误的地方。

详见安装与 OGC 服务概览。

地图方案的公开样式地址返回 404？

方案还没有保存过版本时返回「方案还没有发布版本」，请先在编辑器中「保存版本」；方案 id 写错或方案已删除时返回「方案不存在」。

详见地图方案与工作台。