快速开始（在线）

照着下面 6 步，大约 30 分钟可以完成：注册在线系统，上传一份数据，发布成服务，再用 JS SDK 把它显示在自己的网页上。

开始前请准备一份矢量数据，推荐 GeoPackage（.gpkg）或 Shapefile 压缩包（.zip，至少包含 .shp、.shx、.dbf，最好带 .prj）。手里是 GeoJSON 时，先用 QGIS 或 ogr2ogr 转成 GeoPackage。

1. 注册并创建工作空间

打开在线系统的注册页，用邮箱接收验证码完成注册，然后用邮箱验证码或账号密码登录控制台。

数据、图层和服务都存放在工作空间里。第一次登录后，在左侧导航「管理 → 工作空间」点「新建工作空间」建一个，你就是它的所有者。

预期结果： 工作空间列表里出现刚建的工作空间。

2. 上传数据

点左侧导航顶部的「发布服务」（或按 N）打开发布向导：

在「发布到工作空间」中选第 1 步建的工作空间。
数据来源选「上传文件」，把数据文件拖进上传区或点选文件。平台按文件识别数据类型；100 MB 以上的文件自动分片上传，选择文件夹时会先在浏览器里打成 zip。
上传完成后进入「选择数据」，勾选要发布的图层（可以多选）。

预期结果： 「选择数据」里列出文件中的图层，带几何类型与坐标系。

常见问题：

提示「该类型只接受 … 文件」：扩展名与识别出的类型不符，例如 Shapefile 必须打成 .zip 上传。
列不出图层：Shapefile 压缩包缺 .shx 或 .dbf，或坐标系无法识别（缺 .prj）。

3. 发布服务

在「服务设置」中：

服务名称：只能用小写字母、数字和连字符，出现在服务地址里，发布后不能修改。记下它，第 5 步要用。
服务能力：向导按数据类型预先勾选推荐的能力。矢量数据默认包含 MapServer、FeatureServer 与 VectorTileServer，本教程用到的是 VectorTileServer，请保持勾选。各能力的用途见发布服务。
访问级别：默认「私有」，下一步再决定（也可以在这里直接选好）。

点「确认并发布」核对后发布。向导会创建图层与服务，并自动启动服务。

预期结果： 页面显示「已上线」，列出服务地址和接入代码；点「预览」能看到数据。

常见问题：

提示服务名称已存在：换一个名称。
显示「已发布，正在启动」：服务正在启动，稍等片刻状态会变为「运行中」。
显示「已发布，但启动失败」：到服务详情查看原因，修正后点「重新启动」。

4. 设为公开，或创建 API Key

外部网页要访问这个服务，有两种做法：

设为公开（最简单）：打开服务详情的「设置」页签，「访问级别」选「公开」并保存。任何人无需登录、无需 Key 即可访问。
用 API Key：访问级别选「API Key」并保存；再到「管理 → 工作空间」打开你的工作空间，在「API Key」页签点「新建 API Key」，填写名称后创建。完整的 Key 只显示这一次，请立即复制保存，它形如 gb_xxx…。

预期结果： 服务详情标题旁的徽标显示「公开」或「API Key」。访问级别的修改最长约 30 秒后生效。

5. 用 SDK 在网页上加载

在线系统自带 JS SDK 与 MapLibre 的浏览器版本，都在 https://map-demo.geobridge.cn/geobridge-mapserver/sandbox/vendor/ 下。把以下文件下载到你网页所在目录的 vendor/ 子目录中，保持相同的目录结构：

geobridge-sdk.umd.js
maplibre-gl/maplibre-gl.js、maplibre-gl/maplibre-gl-shared.js、maplibre-gl/maplibre-gl-worker.js、maplibre-gl/maplibre-gl.css

然后新建一个 HTML 文件：

html

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="./vendor/maplibre-gl/maplibre-gl.css" />
  </head>
  <body>
    <div id="map" style="height: 480px"></div>
    <script src="./vendor/geobridge-sdk.umd.js"></script>
    <script type="module">
      import * as maplibregl from './vendor/maplibre-gl/maplibre-gl.js'

      const client = new GeoBridge.GeoBridgeClient({
        baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver',
        apiKey: 'gb_xxx…', // 公开服务删掉这一行
      })
      const path = 'my-roads' // 换成第 3 步的服务名称
      const map = new maplibregl.Map({
        container: 'map',
        style: await client.maplibre.serviceStyle(path),
        transformRequest: client.transformRequest,
      })
      const bounds = await client.services.extent(path)
      if (bounds) map.fitBounds(bounds, { padding: 20 })
    </script>
  </body>
</html>

页面必须通过 http(s) 打开，例如在该目录运行任意静态文件服务器后访问 http://localhost:<端口>/。MapLibre 以模块脚本加载，直接双击用 file:// 打开会失败。

预期结果： 地图显示你的数据，并缩放到数据范围。

常见问题（打开浏览器开发者工具的控制台查看错误）：

现象	原因与处理
错误码 `TOKEN_REQUIRED`（HTTP 401）	服务级别是「API Key」，但请求没有带 Key：检查 `apiKey`
错误码 `TOKEN_INVALID`（HTTP 401）	Key 写错、已撤销或已过期；或 Key 设置了来源域名白名单，而当前页面的域名不在名单内
错误码 `UNAUTHORIZED`（HTTP 401）	服务仍是「私有」，或服务名称写错（平台对匿名访问不透露服务是否存在）
HTTP 503，消息含「已停止」	服务没有启动或被停止：在服务详情点「启动」
地图空白、无报错	确认第 3 步勾选了 VectorTileServer

各错误码的完整说明见错误码。

6. 在沙箱里试运行

不想自己搭页面时，可以用在线沙箱：打开下面的示例，在页面顶部的「平台地址」填 https://map-demo.geobridge.cn/geobridge-mapserver，「API Key」填你的 Key（公开服务可以不填），把代码里的服务路径换成你的服务名称，点「运行」。

在沙箱中打开

在沙箱里请使用未设置来源域名白名单的 Key：沙箱的运行页不带可识别的来源域名，设置了白名单的 Key 在这里一定会被拒绝。沙箱的更多用法见在线沙箱，更多示例见示例总览。

快速开始（在线） ​

1. 注册并创建工作空间 ​

2. 上传数据 ​

3. 发布服务 ​

4. 设为公开，或创建 API Key ​

5. 用 SDK 在网页上加载 ​