Cesium Viewer 的 BaseLayerPicker 控件默认只展示 Bing Maps 等选项，开发者若要切换天地图或高德地图，必须手动注册 ImageryProvider 并处理坐标偏移与 token 合规。信号显示该控件一行配置即可切换，但国产地图接入远不止于此。

BaseLayerPicker 默认仅加载国外底图服务

Cesium 官方 Viewer 实例在初始化时会自动挂载 BaseLayerPicker 控件。该控件在界面右上角以图标形式呈现，点击后弹出底图选择面板。默认情况下，面板只包含几项国外服务：Bing Maps 影像、Bing Maps 道路、Bing Maps 地形阴影以及 Cesium Ion 的部分免费图层。

这些选项全部基于 Web Mercator 投影（EPSG:3857），数据源来自微软 Bing 服务。控件内部通过 ImageryProvider 数组来管理可用图层，初始化代码中若不显式传入额外 provider，BaseLayerPicker 就只会加载这几项。国产地图服务如天地图、高德地图并未被内置，因为它们采用 GCJ-02 坐标系，且需要开发者自行申请访问密钥。

直接把国产地图的 URL 填进控件是无效的。Cesium 不会自动识别天地图的瓦片地址，也不会处理坐标偏移。这导致很多前端开发者第一次尝试时发现切换后地图错位严重，城市轮廓与真实位置偏差可达几百米。信号中明确提到 BaseLayerPicker 是 Cesium 内置的便利控件，但便利仅限于其默认支持的国外服务。

理解默认行为是后续定制的前提。开发者必须先知道控件依赖 ImageryProvider 实例，而非简单 URL 字符串，才能继续往下走。否则后续所有代码都会建立在错误假设上。

通过 ImageryProvider 注册天地图和高德服务

要接入国产地图，首先需要创建对应的 ImageryProvider。Cesium 提供了 UrlTemplateImageryProvider 类来处理标准 XYZ 瓦片服务。

对于天地图，典型配置如下：

1
2
3
4
5
6

const tdtKey = '你的天地图密钥';
const imageryProvider = new Cesium.UrlTemplateImageryProvider({
  url: `https://t0.tianditu.gov.cn/img_w/wmts?layer=img&style=default&tilematrixset=w&Service=WMTS&Request=GetTile&Version=1.0.0&Format=tiles&TileMatrix={z}&TileCol={x}&TileRow={y}&tk=${tdtKey}`,
  tilingScheme: new Cesium.WebMercatorTilingScheme(),
  maximumLevel: 18
});

高德地图接入类似，但 URL 模板不同：

1
2
3
4
5

const gaodeProvider = new Cesium.UrlTemplateImageryProvider({
  url: 'https://webrd02.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&x={x}&y={y}&z={z}',
  tilingScheme: new Cesium.WebMercatorTilingScheme(),
  credit: '高德地图'
});

创建完 provider 后，可以直接把它们加入 Viewer 的 imageryLayers 集合：

1

viewer.imageryLayers.addImageryProvider(imageryProvider);

这一步只是把图层加载进场景。要让 BaseLayerPicker 能切换，还需要后续步骤。信号标题明确把 BaseLayerPicker 与国产地图接入放在一起，说明两者必须结合使用。

实际项目中常把多个 provider 封装成数组，方便后续统一管理。注意高德地图默认使用 GCJ-02 坐标，而 Cesium 内部默认是 Web Mercator，因此下一节要重点解决投影差异。

Web Mercator 与 GCJ-02 投影差异的处理

中国大陆公开地图服务普遍采用 GCJ-02 坐标系，也称火星坐标系。这是国家测绘地理信息局规定的加密偏移算法。Web Mercator 则是国际通用的球面墨卡托投影，两者底图在相同经纬度下会出现明显错位。

偏移量在城市区域通常为 300-500 米，方向大致向北偏东。直接把高德或天地图瓦片当作 Web Mercator 加载，道路和建筑会与 Cesium 的三维模型、矢量数据完全对不上。

常见处理方式有两种。第一种是使用坐标转换库，如 proj4js 或自定义的 GCJ-02 到 WGS84 转换函数，在加载瓦片前对请求的瓦片坐标进行偏移修正。第二种是直接使用支持 Web Mercator 的天地图子服务（天地图提供专门的 web 墨卡托服务）。

代码示例中常看到开发者这样修正：

1
2
3
4

function gcj02ToWGS84(lng, lat) {
  // 实现 GCJ-02 转 WGS84 的公式
  // 这里省略具体算法
}

更推荐的做法是直接请求天地图的 WMTS 服务并指定 Web Mercator 切片集（tilematrixset=w），这样 Cesium 就不需要额外转换。信号建议角度特别强调了投影差异处理，说明这是接入国产地图时最容易踩坑的一点。

开发者必须在项目早期就确定底图坐标系策略，否则后续叠加其他数据源时会反复出现对齐问题。

天地图与高德 token 的合规申请流程

在中国使用在线地图服务必须申请合法 token。天地图密钥通过国家地理信息公共服务平台官网申请，进入开发者中心后注册应用，选择 Web 服务类型，获取 tk 参数。高德地图则在高德开放平台创建应用，选择 Web 端地图服务，获取 key。

申请过程中需要填写应用名称、用途描述，并同意相关服务协议。协议通常要求不得用于非法测绘、不得绕过加密偏移直接输出原始坐标数据。

根据中国地图服务相关政策，未经测绘资质的单位和个人不得从事地理信息采集、处理等活动。普通开发者在网页上展示地图属于合理使用范畴，但如果涉及高精度定位、数据导出或商业测绘用途，就可能触及红线。

token 申请成功后，必须妥善保管，不要直接写死在前端代码里。推荐使用后端代理服务转发瓦片请求，把 token 放在服务器端。信号中提到的合规必要性正是为了提醒开发者不要忽略这一环节。

申请完成后，建议立即测试 token 有效性。过期或配额超限都会导致瓦片返回 403 或 404 错误。

将国产底图选项注入 BaseLayerPicker 控件

BaseLayerPicker 本身支持自定义图层集合。正确做法是创建 ImageryLayerCatalogItem 实例，然后把它们塞进 providerViewModels 数组。

代码大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const providerViewModels = [];

providerViewModels.push(new Cesium.ProviderViewModel({
  name: '天地图影像',
  tooltip: '天地图影像底图',
  iconUrl: 'path/to/tdt-icon.png',
  creationFunction: function() {
    return new Cesium.UrlTemplateImageryProvider({ /* 天地图配置 */ });
  }
}));

// 同样加入高德选项

const baseLayerPicker = new Cesium.BaseLayerPicker(viewer, {
  globe: viewer.scene.globe,
  imageryProviderViewModels: providerViewModels
});

这样用户点击右上角图标时，就能看到天地图和高德选项。切换时控件会自动移除旧图层、加载新图层。信号摘要中提到“一行配置即可切换”，指的就是这种封装后的便利性。

图标建议使用 64x64 的 PNG 图片，保持界面风格一致。也可以把常用组合做成“天地图影像+注记”“高德道路”等多个视图模型，方便用户快速选择。

完成这一步后，BaseLayerPicker 就从默认的国外服务面板变成了真正支持国产地图的切换工具。

前端 GIS 开发者接入后的合规风险与落地建议

不申请 token 直接使用公开瓦片地址，虽然短期能跑通演示，但存在被服务商封禁 IP、法律合规风险。部分企业用户曾因未备案直接调用高德服务而收到警告函。

更严重的风险在于，如果项目后续涉及位置大数据分析、无人机航测等，可能被认定为非法测绘。建议所有面向中国市场的 Cesium 项目都在技术方案评审阶段把地图合规列入检查项。

落地建议包括：

  1. 优先使用有官方 Web Mercator 支持的天地图服务，减少坐标转换复杂度；
  2. 把 token 和瓦片请求放在自家后端代理，防止前端代码泄露密钥；
  3. 在用户协议或隐私政策中说明地图数据来源和使用方式；
  4. 对于需要高精度的场景，考虑购买专业测绘数据或申请测绘资质。

对前端和 GIS 开发者而言，掌握 Cesium 国产地图接入能力是必备技能。国内绝大多数 WebGIS 项目最终都会落地到天地图、高德或百度地图上。把 BaseLayerPicker 改造好，不仅提升了用户体验，也降低了后续维护成本。

实际项目中还可进一步扩展，把图层切换与图例、透明度控制结合起来，形成完整底图管理模块。信号提供的案例正是帮助开发者从默认控件走向实用落地的路径。

整个接入过程虽然比国外服务多出投影和合规两道关，但完成后能显著提升产品在国内环境的可用性。开发者应尽早完成 token 申请和测试，避免项目后期因合规问题返工。

参考来源