简介基于Vue3TypeScriptVite与Cesium构建的天地图加载示例面向需要快速上手三维地图应用的前端开发者解决在Vue3工程化环境下集成Cesium并实现天地图影像与标注多服务器随机加载切换的实际需求。压缩包共16个文件以ts、vue、json等类型为主包含Vite配置、TypeScript类型声明、App.vue与HelloWorld.vue组件、天地图图层加载逻辑、静态图标资源以及样式文件整体仅21KB小巧精炼适合作为项目脚手架进行扩展改造。已有3008人学习下载适合正在搭建Cesium地图项目或希望借鉴多服务器负载均衡切换方案的开发者。资源提供了完整的示例代码与清晰的项目目录结构从环境配置到核心代码一目了然可帮助读者快速理解Cesium与Vue3的组合式集成方式深入掌握天地图多服务器地址随机切换的实现思路避免重复踩坑大幅提升地图类项目的开发效率。 最近在做一个三维GIS项目技术栈是 Vue3 Vite TypeScript Cesium需求本身不复杂但有个细节挺有意思要同时加载天地图影像和标注图层并且不能只固定用一个服务器而是要让地图从多个天地图服务地址里随机拉取还支持随时切换版本。这里说的“版本”不是代码版本而是地图底图样式版本比如影像版、矢量版以及是否叠加中文标注。这篇文章就围绕这个场景把我踩过的坑和最终落地的方案完整写出来。适合那些刚开始在 Vue3 生态里集成 Cesium或者想用天地图做底图又不想被单个服务器拖垮的朋友。1. 项目背景与整体设计思路这个需求拆开看其实分成四件事第一用天地图的 WMTS 服务作为三维场景的底图第二在底图上叠加天地图的标注图层第三实现多服务器随机调度避免所有请求打到一个域名上第四做一个可以切换底图版本和标注显隐的交互。很多人可能觉得天地图就一个 url直接 new 一个 ImageryProvider 就行但实际放到生产环境之后单一服务器会面临负载、限流、跨域不稳定等一系列问题。天地图官方提供了 t0 到 t7 八个 WMTS 服务域名目的是让客户端能分散到不同节点上。大多数示例代码都是写死一个域名这在小项目里没问题但一旦地图访问量上来或者公司内网与公网网络环境复杂写死域名就会遇到莫名其妙的卡顿和白屏。我的做法是维护一个服务器地址池每次初始化地图时随机选一个同时提供手动切换入口用来应对特定网络环境下某个域名不可达的情况。1.1 核心需求拆解这个项目表面看起来只是“加载一个地图”但实际拆分后至少包含四个独立模块影像底图加载天地图影像底图img_w作为全球影像背景。标注叠加加载中文注记图层cia_w叠加在影像上用于显示地名、路网名称。多服务器随机至少配置 t0-t7 域名池随机负载避免单点故障。版本切换底图支持影像版和矢量版切换标注图层独立显隐控制。这种拆法不是拍脑袋而是为了后面封装代码时模块足够清晰。比如标注图层和底图图层分离之后切换底图版本时就不会误删标注层多服务器随机逻辑也只需要在配置层维护。1.2 为什么是这套技术栈Vue3 TypeScript 的组合不用多说项目要长期维护、多人协作类型约束能省掉很多低级问题。Vite 主要是启动快Cesium 是个体积不小的库Vite 的依赖预构建能力能让开发服务器启动时间平均缩短 30% 以上这在频繁调试地图样式时收益很大。Cesium 本身可以支持 script 标签引入但在工程化项目里我更推荐用vite-plugin-cesium插件。这个插件会帮你把 Cesium 的静态资源、Worker、组件库统一处理好不需要手动拷贝Build/Cesium/Workers之类的目录。如果你用过旧版 Webpack 配 Cesium就知道这一步有多痛苦。2. 环境准备与项目初始化环境搭建是整个项目最容易出问题的一环尤其是 Cesium 配合 Vite 时很多人在第一步就被插件版本、worker 路径、资源加载 404 折腾很久。我直接给出我验证过的配置。2.1 创建 Vue3 TS Vite 项目使用 Vite 官方脚手架创建项目模板选vue-tsnpm create vitelatest tianditu-cesium -- --template vue-ts cd tianditu-cesium npm install这里有个细节Vite 版本建议选 4 以上vite-plugin-cesium对 Vite 5、6 的兼容性已经相当稳定。如果遇到插件 API 冲突先检查一下是否把 Vite 锁在了 2.x 的老版本。2.2 集成 Cesium安装 Cesium 本体和 Vite 插件npm install cesium npm install -D vite-plugin-cesium然后在vite.config.ts中配置import { defineConfig } from vite import vue from vitejs/plugin-vue import cesium from vite-plugin-cesium export default defineConfig({ plugins: [ vue(), cesium() ] })这个插件会自动注入 Cesium 的按需编译配置最关键的是它会处理CESIUM_BASE_URL让 Cesium 在运行时能正确找到Assets、Workers、Widgets等静态资源。如果不配置你会在控制台看到一堆 404 报错。2.3 配置天地图 Token天地图的数据服务需要申请一个 Token官方控制台申请之后会绑定域名白名单。开发环境和生产环境如果是不同域名需要分别把域名加进去否则请求直接 403。在项目根目录创建.env.development文件VITE_TIANDITU_TOKEN你的token在代码里通过import.meta.env.VITE_TIANDITU_TOKEN读取。注意 Vite 只暴露以VITE_开头的变量给前端代码所以命名不要省略前缀。注意Token 一旦泄露可能会被他人盗用建议在天地图后台开启域名白名单并且定期更换。3. 天地图服务的加载原理与多服务器随机策略想要实现多服务器随机加载首先得弄明白天地图 WMTS 服务的地址结构。很多人图省事直接复制官方示例里的固定 URL一旦遇到服务器节点波动就束手无策。3.1 理解天地图 WMTS 接口天地图 WMTS 服务地址格式大致是这样https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimg_wSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的tokenCesium 中可以用UrlTemplateImageryProvider直接适配这种瓦片地址它会把{z}、{x}、{y}自动替换成当前视角下的瓦片编号不需要额外解析 WMTS Capabilities 文档。常用的图层类型主要有四个图层类型说明典型用途img_w全球影像底图影像底图cia_w影像中文注记叠加在影像上的地名路网vec_w全球矢量底图矢量底图cva_w矢量中文注记叠加在矢量底图上的标注我的项目里影像版底图 img_w cia_w矢量版底图 vec_w cva_w。切换版本时本质上就是切换LAYER参数。3.2 多服务器随机加载实现天地图域名从 t0 到 t7 一共八个节点我们可以把这些节点组成服务器地址池const TIANDITU_SERVERS Array.from({ length: 8 }, (_, i) https://t${i}.tianditu.gov.cn) function getRandomServer(): string { const index Math.floor(Math.random() * TIANDITU_SERVERS.length) return TIANDITU_SERVERS[index] }为什么要随机而不是按顺序轮询因为如果所有用户都从 t0 开始加载t0 节点很容易成为瓶颈随机分布能让请求在八个节点之间相对均衡。Math.random()在这里完全够用不需要加密级随机数。然后在生成瓦片 URL 时拼接服务器地址const server getRandomServer() const url ${server}/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimg_wSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${token}多服务器随机带来的另一个好处是当某个节点出现网络抖动时用户刷新页面后有概率切换到其他可用节点等于做了一次最粗粒度的容灾。3.3 影像/标注版本切换的思路“版本切换”在代码层面需要区分两层底图图层和标注图层。Cesium 里一个ImageryLayer可以控制透明度、显隐但如果你要切换底图类型比如从影像切到矢量建议先移除旧底图层再添加新底图层避免两个影像层叠在一起。标注层则独立控制显隐annotationLayer.show true / false这里有一个关键点切换底图时要同步切换对应的标注类型。影像版配cia_w矢量版配cva_w。如果切到矢量底图后还保留影像注记地名样式会显得很突兀。4. 代码实现封装一个可复用的地图模块如果只是在组件里写几行加载代码后期维护会非常痛苦。我的做法是把天地图相关逻辑封装成一个TiandituLayerManager类职责清晰复用性也高。4.1 配置与工具类封装新建src/utils/tianditu.tsimport * as Cesium from cesium export type TiandituLayerType img_w | vec_w export type TiandituAnnotationType cia_w | cva_w const TIANDITU_SERVER_POOL Array.from({ length: 8 }, (_, i) https://t${i}.tianditu.gov.cn) export class TiandituLayerManager { private viewer: Cesium.Viewer private token: string private baseServer: string constructor(viewer: Cesium.Viewer, token: string) { this.viewer viewer this.token token this.baseServer this.getRandomServer() } private getRandomServer(): string { const index Math.floor(Math.random() * TIANDITU_SERVER_POOL.length) return TIANDITU_SERVER_POOL[index] } private buildUrl(layer: string): string { const params new URLSearchParams({ SERVICE: WMTS, REQUEST: GetTile, VERSION: 1.0.0, LAYER: layer, STYLE: default, TILEMATRIXSET: w, FORMAT: tiles, TILEMATRIX: {z}, TILEROW: {y}, TILECOL: {x}, tk: this.token }) return ${this.baseServer}/${layer}/wmts?${params.toString()} } addBaseLayer(layerType: TiandituLayerType img_w): Cesium.ImageryLayer { const provider new Cesium.UrlTemplateImageryProvider({ url: this.buildUrl(layerType), maximumLevel: 18 }) const layer this.viewer.imageryLayers.addImageryProvider(provider) layer.id base_${layerType} return layer } addAnnotationLayer(annotationType: TiandituAnnotationType cia_w): Cesium.ImageryLayer { const provider new Cesium.UrlTemplateImageryProvider({ url: this.buildUrl(annotationType), maximumLevel: 18 }) const layer this.viewer.imageryLayers.addImageryProvider(provider) layer.id annotation_${annotationType} return layer } refreshServer(): string { this.baseServer this.getRandomServer() return this.baseServer } }构造函数里传入viewer和token每次初始化时自动随机选一个服务器。buildUrl方法使用URLSearchParams生成参数避免手写字符串拼接时漏掉某个参数。4.2 在 Vue 组件中集成新建src/components/MapView.vue在onMounted里初始化 Cesium Viewer然后加载图层template div classmap-container div idcesiumContainer classcesium-container/div div classmap-toolbar button clickswitchBase(img_w)影像底图/button button clickswitchBase(vec_w)矢量底图/button button clicktoggleAnnotation 标注{{ annotationVisible ? 开 : 关 }} /button button clickrefreshServer切换服务器/button /div /div /template script setup langts import { onMounted, onUnmounted, ref } from vue import * as Cesium from cesium import { TiandituLayerManager } from /utils/tianditu const annotationVisible ref(true) let viewer: Cesium.Viewer let manager: TiandituLayerManager let currentBaseType: img_w | vec_w img_w onMounted(() { viewer new Cesium.Viewer(cesiumContainer, { animation: false, timeline: false, geocoder: false, baseLayerPicker: false, infoBox: false, selectionIndicator: false, navigationHelpButton: false, }) manager new TiandituLayerManager(viewer, import.meta.env.VITE_TIANDITU_TOKEN) manager.addBaseLayer(img_w) manager.addAnnotationLayer(cia_w) }) const switchBase (type: img_w | vec_w) { currentBaseType type removeBaseLayers() manager.addBaseLayer(type) if (annotationVisible.value) { const annotationType type img_w ? cia_w : cva_w removeAnnotationLayers() manager.addAnnotationLayer(annotationType) } } const toggleAnnotation () { annotationVisible.value !annotationVisible.value const layers viewer.imageryLayers._layers for (let i 0; i layers.length; i) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(annotation_)) { layer.show annotationVisible.value } } } const refreshServer () { const server manager.refreshServer() switchBase(currentBaseType) console.log(当前服务器节点, server) } const removeBaseLayers () { const layers viewer.imageryLayers._layers for (let i layers.length - 1; i 0; i--) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(base_)) { viewer.imageryLayers.remove(layer) } } } const removeAnnotationLayers () { const layers viewer.imageryLayers._layers for (let i layers.length - 1; i 0; i--) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(annotation_)) { viewer.imageryLayers.remove(layer) } } } onUnmounted(() { if (viewer) { viewer.destroy() } }) /script这里有几个容易踩的坑。第一viewer.imageryLayers._layers是私有属性虽然实际访问没问题但最好封装到管理器内部避免组件层散落大量数组遍历逻辑。第二switchBase里我先移除旧底图再添加新底图否则两个底图图层叠加时会出现闪烁和层级错乱。第三标注图层独立控制show所以切换底图时不会误删标注。4.3 多服务器“切换版本”的完整流程当你点击“切换服务器”按钮时实际上执行的是重新随机一个服务器地址然后移除当前所有底图和标注再用新的服务器地址重新添加。这套流程确保新请求全部落到新节点上不会残留旧服务器的瓦片缓存。如果你希望更平滑地切换可以在移除图层前添加一个淡入淡出动画但 Cesium 原生 API 对这一层的控制并不完整我目前是直接替换用户感知反而更明确。5. 常见问题与排查技巧实录代码写完之后运行过程中会遇到各种问题这里整理几个最高频的排查场景。5.1 加载天地图显示空白遇到空白先打开浏览器的 Network 面板看请求状态码。如果返回 403几乎可以肯定是 Token 的域名白名单没配好。如果是 200 但瓦片显示不出来检查一下瓦片 URL 参数是否完整尤其是TILEMATRIXSETw这个参数少了他天地图服务端会返回异常数据。另一个常见问题是maximumLevel设置过大。天地图影像最大支持 18 级超过这个级别的瓦片请求会返回空数据地图看起来就像“突然空白”。在UrlTemplateImageryProvider里显式设置maximumLevel: 18可以规避。5.2 TS 类型报错与 Cesium 类型问题新版本 Cesium 自带类型声明不需要再安装types/cesium。如果 IDE 提示找不到编辑器组件把vite-env.d.ts里/// reference typesvite/client /保留好。另外使用import * as Cesium from cesium时尽量不要再使用Cesium.Ion相关功能因为默认 Viewer 会尝试请求 Cesium Ion 的默认底图没有配置 Ion Token 就会出现网络请求失败。在初始化 Viewer 时把baseLayerPicker设为 false并主动removeAll()默认影像层。5.3 Vite 打包优化esbuild 与 terser 的区别Vite 默认使用 esbuild 做代码压缩速度极快但压缩率相对较低。如果用 Cesium 这种体积比较大的库可以在vite.config.ts里切换成 terserexport default defineConfig({ build: { minify: terser, terserOptions: { compress: { drop_console: true, drop_debugger: true } } } })terser 压缩率更高但构建时间会明显增加。我的建议是开发环境保持默认 esbuild生产构建时如果产物超过 5MB再考虑切 terser。Cesium 本身有 gzip 压缩很多情况下 esbuild 已经够用。5.4 多服务器切换后重复叠加图层这是封装不全时最容易出现的问题。很多人切换服务器时只改了 URL没有移除旧图层导致一个影像层叠一个影像层场景颜色越来越深显存占用飙升。解决思路就是我在TiandituLayerManager里做的给图层写id按base_、annotation_前缀区分切换前先移除对应类别的旧图层。不要试图用viewer.imageryLayers.removeAll()一把梭那样会把标注层也删掉还得重建。5.5 Viewer 销毁时的地狱模式onUnmounted里一定要执行viewer.destroy()否则组件切换后Cesium 的渲染循环没有被清理控制台会持续报 WebGL 上下文丢失错误。这是这类项目最常见的“页面卡死”原因。6. 写在最后的一点个人体会这套方案我已经在两个项目里完整落地整体稳定。要说最值得总结的地方不是代码技巧而是“先搞清楚服务再动手封装”。天地图虽然是一个免费服务但它的节点分布、图层类型、参数要求都有完整文档多花半小时读文档后面能省出三天排查时间。另外多服务器随机加载只是最基础的容灾手段如果你的项目真的对地图可用性要求很高建议在refreshServer里加一层节点连通性检测比如先fetch一下t0.tianditu.gov.cn的瓦片头失败就切换下一个节点。我在内网环境遇到过某个节点被防火墙拦截的情况加了检测之后地图加载的成功率明显提升。最后再分享一个小技巧初始化 Cesium Viewer 时如果工程里用到了import.meta.env注意在tsconfig.json里配置types: [vite/client]这样 TypeScript 才能正确识别环境变量类型否则会报Property env does not exist on type ImportMeta。这个报错很不起眼但足以让新手卡半小时。希望这篇文章能帮你少走点弯路。本文还有配套的精品资源点击获取
Vue3+Cesium集成天地图：多服务器随机加载与版本切换实践
简介基于Vue3TypeScriptVite与Cesium构建的天地图加载示例面向需要快速上手三维地图应用的前端开发者解决在Vue3工程化环境下集成Cesium并实现天地图影像与标注多服务器随机加载切换的实际需求。压缩包共16个文件以ts、vue、json等类型为主包含Vite配置、TypeScript类型声明、App.vue与HelloWorld.vue组件、天地图图层加载逻辑、静态图标资源以及样式文件整体仅21KB小巧精炼适合作为项目脚手架进行扩展改造。已有3008人学习下载适合正在搭建Cesium地图项目或希望借鉴多服务器负载均衡切换方案的开发者。资源提供了完整的示例代码与清晰的项目目录结构从环境配置到核心代码一目了然可帮助读者快速理解Cesium与Vue3的组合式集成方式深入掌握天地图多服务器地址随机切换的实现思路避免重复踩坑大幅提升地图类项目的开发效率。 最近在做一个三维GIS项目技术栈是 Vue3 Vite TypeScript Cesium需求本身不复杂但有个细节挺有意思要同时加载天地图影像和标注图层并且不能只固定用一个服务器而是要让地图从多个天地图服务地址里随机拉取还支持随时切换版本。这里说的“版本”不是代码版本而是地图底图样式版本比如影像版、矢量版以及是否叠加中文标注。这篇文章就围绕这个场景把我踩过的坑和最终落地的方案完整写出来。适合那些刚开始在 Vue3 生态里集成 Cesium或者想用天地图做底图又不想被单个服务器拖垮的朋友。1. 项目背景与整体设计思路这个需求拆开看其实分成四件事第一用天地图的 WMTS 服务作为三维场景的底图第二在底图上叠加天地图的标注图层第三实现多服务器随机调度避免所有请求打到一个域名上第四做一个可以切换底图版本和标注显隐的交互。很多人可能觉得天地图就一个 url直接 new 一个 ImageryProvider 就行但实际放到生产环境之后单一服务器会面临负载、限流、跨域不稳定等一系列问题。天地图官方提供了 t0 到 t7 八个 WMTS 服务域名目的是让客户端能分散到不同节点上。大多数示例代码都是写死一个域名这在小项目里没问题但一旦地图访问量上来或者公司内网与公网网络环境复杂写死域名就会遇到莫名其妙的卡顿和白屏。我的做法是维护一个服务器地址池每次初始化地图时随机选一个同时提供手动切换入口用来应对特定网络环境下某个域名不可达的情况。1.1 核心需求拆解这个项目表面看起来只是“加载一个地图”但实际拆分后至少包含四个独立模块影像底图加载天地图影像底图img_w作为全球影像背景。标注叠加加载中文注记图层cia_w叠加在影像上用于显示地名、路网名称。多服务器随机至少配置 t0-t7 域名池随机负载避免单点故障。版本切换底图支持影像版和矢量版切换标注图层独立显隐控制。这种拆法不是拍脑袋而是为了后面封装代码时模块足够清晰。比如标注图层和底图图层分离之后切换底图版本时就不会误删标注层多服务器随机逻辑也只需要在配置层维护。1.2 为什么是这套技术栈Vue3 TypeScript 的组合不用多说项目要长期维护、多人协作类型约束能省掉很多低级问题。Vite 主要是启动快Cesium 是个体积不小的库Vite 的依赖预构建能力能让开发服务器启动时间平均缩短 30% 以上这在频繁调试地图样式时收益很大。Cesium 本身可以支持 script 标签引入但在工程化项目里我更推荐用vite-plugin-cesium插件。这个插件会帮你把 Cesium 的静态资源、Worker、组件库统一处理好不需要手动拷贝Build/Cesium/Workers之类的目录。如果你用过旧版 Webpack 配 Cesium就知道这一步有多痛苦。2. 环境准备与项目初始化环境搭建是整个项目最容易出问题的一环尤其是 Cesium 配合 Vite 时很多人在第一步就被插件版本、worker 路径、资源加载 404 折腾很久。我直接给出我验证过的配置。2.1 创建 Vue3 TS Vite 项目使用 Vite 官方脚手架创建项目模板选vue-tsnpm create vitelatest tianditu-cesium -- --template vue-ts cd tianditu-cesium npm install这里有个细节Vite 版本建议选 4 以上vite-plugin-cesium对 Vite 5、6 的兼容性已经相当稳定。如果遇到插件 API 冲突先检查一下是否把 Vite 锁在了 2.x 的老版本。2.2 集成 Cesium安装 Cesium 本体和 Vite 插件npm install cesium npm install -D vite-plugin-cesium然后在vite.config.ts中配置import { defineConfig } from vite import vue from vitejs/plugin-vue import cesium from vite-plugin-cesium export default defineConfig({ plugins: [ vue(), cesium() ] })这个插件会自动注入 Cesium 的按需编译配置最关键的是它会处理CESIUM_BASE_URL让 Cesium 在运行时能正确找到Assets、Workers、Widgets等静态资源。如果不配置你会在控制台看到一堆 404 报错。2.3 配置天地图 Token天地图的数据服务需要申请一个 Token官方控制台申请之后会绑定域名白名单。开发环境和生产环境如果是不同域名需要分别把域名加进去否则请求直接 403。在项目根目录创建.env.development文件VITE_TIANDITU_TOKEN你的token在代码里通过import.meta.env.VITE_TIANDITU_TOKEN读取。注意 Vite 只暴露以VITE_开头的变量给前端代码所以命名不要省略前缀。注意Token 一旦泄露可能会被他人盗用建议在天地图后台开启域名白名单并且定期更换。3. 天地图服务的加载原理与多服务器随机策略想要实现多服务器随机加载首先得弄明白天地图 WMTS 服务的地址结构。很多人图省事直接复制官方示例里的固定 URL一旦遇到服务器节点波动就束手无策。3.1 理解天地图 WMTS 接口天地图 WMTS 服务地址格式大致是这样https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimg_wSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的tokenCesium 中可以用UrlTemplateImageryProvider直接适配这种瓦片地址它会把{z}、{x}、{y}自动替换成当前视角下的瓦片编号不需要额外解析 WMTS Capabilities 文档。常用的图层类型主要有四个图层类型说明典型用途img_w全球影像底图影像底图cia_w影像中文注记叠加在影像上的地名路网vec_w全球矢量底图矢量底图cva_w矢量中文注记叠加在矢量底图上的标注我的项目里影像版底图 img_w cia_w矢量版底图 vec_w cva_w。切换版本时本质上就是切换LAYER参数。3.2 多服务器随机加载实现天地图域名从 t0 到 t7 一共八个节点我们可以把这些节点组成服务器地址池const TIANDITU_SERVERS Array.from({ length: 8 }, (_, i) https://t${i}.tianditu.gov.cn) function getRandomServer(): string { const index Math.floor(Math.random() * TIANDITU_SERVERS.length) return TIANDITU_SERVERS[index] }为什么要随机而不是按顺序轮询因为如果所有用户都从 t0 开始加载t0 节点很容易成为瓶颈随机分布能让请求在八个节点之间相对均衡。Math.random()在这里完全够用不需要加密级随机数。然后在生成瓦片 URL 时拼接服务器地址const server getRandomServer() const url ${server}/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimg_wSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${token}多服务器随机带来的另一个好处是当某个节点出现网络抖动时用户刷新页面后有概率切换到其他可用节点等于做了一次最粗粒度的容灾。3.3 影像/标注版本切换的思路“版本切换”在代码层面需要区分两层底图图层和标注图层。Cesium 里一个ImageryLayer可以控制透明度、显隐但如果你要切换底图类型比如从影像切到矢量建议先移除旧底图层再添加新底图层避免两个影像层叠在一起。标注层则独立控制显隐annotationLayer.show true / false这里有一个关键点切换底图时要同步切换对应的标注类型。影像版配cia_w矢量版配cva_w。如果切到矢量底图后还保留影像注记地名样式会显得很突兀。4. 代码实现封装一个可复用的地图模块如果只是在组件里写几行加载代码后期维护会非常痛苦。我的做法是把天地图相关逻辑封装成一个TiandituLayerManager类职责清晰复用性也高。4.1 配置与工具类封装新建src/utils/tianditu.tsimport * as Cesium from cesium export type TiandituLayerType img_w | vec_w export type TiandituAnnotationType cia_w | cva_w const TIANDITU_SERVER_POOL Array.from({ length: 8 }, (_, i) https://t${i}.tianditu.gov.cn) export class TiandituLayerManager { private viewer: Cesium.Viewer private token: string private baseServer: string constructor(viewer: Cesium.Viewer, token: string) { this.viewer viewer this.token token this.baseServer this.getRandomServer() } private getRandomServer(): string { const index Math.floor(Math.random() * TIANDITU_SERVER_POOL.length) return TIANDITU_SERVER_POOL[index] } private buildUrl(layer: string): string { const params new URLSearchParams({ SERVICE: WMTS, REQUEST: GetTile, VERSION: 1.0.0, LAYER: layer, STYLE: default, TILEMATRIXSET: w, FORMAT: tiles, TILEMATRIX: {z}, TILEROW: {y}, TILECOL: {x}, tk: this.token }) return ${this.baseServer}/${layer}/wmts?${params.toString()} } addBaseLayer(layerType: TiandituLayerType img_w): Cesium.ImageryLayer { const provider new Cesium.UrlTemplateImageryProvider({ url: this.buildUrl(layerType), maximumLevel: 18 }) const layer this.viewer.imageryLayers.addImageryProvider(provider) layer.id base_${layerType} return layer } addAnnotationLayer(annotationType: TiandituAnnotationType cia_w): Cesium.ImageryLayer { const provider new Cesium.UrlTemplateImageryProvider({ url: this.buildUrl(annotationType), maximumLevel: 18 }) const layer this.viewer.imageryLayers.addImageryProvider(provider) layer.id annotation_${annotationType} return layer } refreshServer(): string { this.baseServer this.getRandomServer() return this.baseServer } }构造函数里传入viewer和token每次初始化时自动随机选一个服务器。buildUrl方法使用URLSearchParams生成参数避免手写字符串拼接时漏掉某个参数。4.2 在 Vue 组件中集成新建src/components/MapView.vue在onMounted里初始化 Cesium Viewer然后加载图层template div classmap-container div idcesiumContainer classcesium-container/div div classmap-toolbar button clickswitchBase(img_w)影像底图/button button clickswitchBase(vec_w)矢量底图/button button clicktoggleAnnotation 标注{{ annotationVisible ? 开 : 关 }} /button button clickrefreshServer切换服务器/button /div /div /template script setup langts import { onMounted, onUnmounted, ref } from vue import * as Cesium from cesium import { TiandituLayerManager } from /utils/tianditu const annotationVisible ref(true) let viewer: Cesium.Viewer let manager: TiandituLayerManager let currentBaseType: img_w | vec_w img_w onMounted(() { viewer new Cesium.Viewer(cesiumContainer, { animation: false, timeline: false, geocoder: false, baseLayerPicker: false, infoBox: false, selectionIndicator: false, navigationHelpButton: false, }) manager new TiandituLayerManager(viewer, import.meta.env.VITE_TIANDITU_TOKEN) manager.addBaseLayer(img_w) manager.addAnnotationLayer(cia_w) }) const switchBase (type: img_w | vec_w) { currentBaseType type removeBaseLayers() manager.addBaseLayer(type) if (annotationVisible.value) { const annotationType type img_w ? cia_w : cva_w removeAnnotationLayers() manager.addAnnotationLayer(annotationType) } } const toggleAnnotation () { annotationVisible.value !annotationVisible.value const layers viewer.imageryLayers._layers for (let i 0; i layers.length; i) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(annotation_)) { layer.show annotationVisible.value } } } const refreshServer () { const server manager.refreshServer() switchBase(currentBaseType) console.log(当前服务器节点, server) } const removeBaseLayers () { const layers viewer.imageryLayers._layers for (let i layers.length - 1; i 0; i--) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(base_)) { viewer.imageryLayers.remove(layer) } } } const removeAnnotationLayers () { const layers viewer.imageryLayers._layers for (let i layers.length - 1; i 0; i--) { const layer layers[i] as Cesium.ImageryLayer if (String(layer.id).startsWith(annotation_)) { viewer.imageryLayers.remove(layer) } } } onUnmounted(() { if (viewer) { viewer.destroy() } }) /script这里有几个容易踩的坑。第一viewer.imageryLayers._layers是私有属性虽然实际访问没问题但最好封装到管理器内部避免组件层散落大量数组遍历逻辑。第二switchBase里我先移除旧底图再添加新底图否则两个底图图层叠加时会出现闪烁和层级错乱。第三标注图层独立控制show所以切换底图时不会误删标注。4.3 多服务器“切换版本”的完整流程当你点击“切换服务器”按钮时实际上执行的是重新随机一个服务器地址然后移除当前所有底图和标注再用新的服务器地址重新添加。这套流程确保新请求全部落到新节点上不会残留旧服务器的瓦片缓存。如果你希望更平滑地切换可以在移除图层前添加一个淡入淡出动画但 Cesium 原生 API 对这一层的控制并不完整我目前是直接替换用户感知反而更明确。5. 常见问题与排查技巧实录代码写完之后运行过程中会遇到各种问题这里整理几个最高频的排查场景。5.1 加载天地图显示空白遇到空白先打开浏览器的 Network 面板看请求状态码。如果返回 403几乎可以肯定是 Token 的域名白名单没配好。如果是 200 但瓦片显示不出来检查一下瓦片 URL 参数是否完整尤其是TILEMATRIXSETw这个参数少了他天地图服务端会返回异常数据。另一个常见问题是maximumLevel设置过大。天地图影像最大支持 18 级超过这个级别的瓦片请求会返回空数据地图看起来就像“突然空白”。在UrlTemplateImageryProvider里显式设置maximumLevel: 18可以规避。5.2 TS 类型报错与 Cesium 类型问题新版本 Cesium 自带类型声明不需要再安装types/cesium。如果 IDE 提示找不到编辑器组件把vite-env.d.ts里/// reference typesvite/client /保留好。另外使用import * as Cesium from cesium时尽量不要再使用Cesium.Ion相关功能因为默认 Viewer 会尝试请求 Cesium Ion 的默认底图没有配置 Ion Token 就会出现网络请求失败。在初始化 Viewer 时把baseLayerPicker设为 false并主动removeAll()默认影像层。5.3 Vite 打包优化esbuild 与 terser 的区别Vite 默认使用 esbuild 做代码压缩速度极快但压缩率相对较低。如果用 Cesium 这种体积比较大的库可以在vite.config.ts里切换成 terserexport default defineConfig({ build: { minify: terser, terserOptions: { compress: { drop_console: true, drop_debugger: true } } } })terser 压缩率更高但构建时间会明显增加。我的建议是开发环境保持默认 esbuild生产构建时如果产物超过 5MB再考虑切 terser。Cesium 本身有 gzip 压缩很多情况下 esbuild 已经够用。5.4 多服务器切换后重复叠加图层这是封装不全时最容易出现的问题。很多人切换服务器时只改了 URL没有移除旧图层导致一个影像层叠一个影像层场景颜色越来越深显存占用飙升。解决思路就是我在TiandituLayerManager里做的给图层写id按base_、annotation_前缀区分切换前先移除对应类别的旧图层。不要试图用viewer.imageryLayers.removeAll()一把梭那样会把标注层也删掉还得重建。5.5 Viewer 销毁时的地狱模式onUnmounted里一定要执行viewer.destroy()否则组件切换后Cesium 的渲染循环没有被清理控制台会持续报 WebGL 上下文丢失错误。这是这类项目最常见的“页面卡死”原因。6. 写在最后的一点个人体会这套方案我已经在两个项目里完整落地整体稳定。要说最值得总结的地方不是代码技巧而是“先搞清楚服务再动手封装”。天地图虽然是一个免费服务但它的节点分布、图层类型、参数要求都有完整文档多花半小时读文档后面能省出三天排查时间。另外多服务器随机加载只是最基础的容灾手段如果你的项目真的对地图可用性要求很高建议在refreshServer里加一层节点连通性检测比如先fetch一下t0.tianditu.gov.cn的瓦片头失败就切换下一个节点。我在内网环境遇到过某个节点被防火墙拦截的情况加了检测之后地图加载的成功率明显提升。最后再分享一个小技巧初始化 Cesium Viewer 时如果工程里用到了import.meta.env注意在tsconfig.json里配置types: [vite/client]这样 TypeScript 才能正确识别环境变量类型否则会报Property env does not exist on type ImportMeta。这个报错很不起眼但足以让新手卡半小时。希望这篇文章能帮你少走点弯路。本文还有配套的精品资源点击获取
代码包深度解析与实践指南)
