当前位置： 首页 > news >正文

Cesium 9 ，Cesium 离线地图本地实现与服务器部署（ Vue + Cesium 多项目共享离线地图切片部署实践 ）

news 2025/7/15 5:34:35

目录

前言
一、实际背景
1.1 项目结构
1.2 端口配置
1.3 配置简述
二、本地实现
2.1 本地环境
2.2 具体实现
2.2.1 初始配置
2.2.2 加载切片
2.2.3 统一好处
2.2.4 完整代码
三、实际部署
2.1 端口 80 项目
2.2 端口 81 项目
2.3 路径说明
2.4 其它配置
四、常见问题
4.1 未加载地图层
4.2 调试建议
4.3 测试路径
4.4 权限跨域
五、注意事项
六、本文总结
七、更多操作

前言

在 Vue 与 Cesium 三维可视化开发中，使用离线地图切片是提升加载性能、减少外网依赖的关键手段。尤其在内网部署或无网络环境中（如封闭园区、应急现场、保密系统等），本地地图切片不仅能加快数据加载速度，还能确保系统在断网情况下依然稳定运行，具有重要的实际意义。

在实际部署中，一台服务器上常会运行多个前端项目（如大屏系统 bigscreen 和管理系统 system），它们往往需要共用同一套地图切片资源。通过合理配置 Nginx，可实现地图资源的统一托管与多项目共享，提高部署效率与维护便捷性。

本文将从目录结构设计、Nginx 配置、Cesium 调用方式等方面，完整讲解如何实现多个项目共享一套离线地图切片资源，适用于各类内网或离线场景下的三维地理信息系统建设。

一、实际背景

项目结构与部署环境

1.1 项目结构

项目目录结构

假设服务器中 Nginx 的根目录为 /usr/local/nginx/html/，文件结构如下：

/usr/local/nginx/html/
├── bigscreen/     ← Vue 大屏项目打包目录
├── system/        ← Vue 管理系统打包目录
├── tiles/         ← 离线地图切片目录
│   ├── imagery/   ← 卫星底图（.jpg）
│   └── label/     ← 中文标签图层（.png）

这里的 tiles 文件，就是地图切片文件，是在网上（淘宝）买的。自己准备好地图切片。

1.2 端口配置

端口与服务配置

  1. system 项目部署在 80 端口

  2. bigscreen 项目部署在 81 端口

  3. 地图切片 /tiles/ 路径由两个端口共用

1.3 配置简述

Nginx 配置结构简述

Nginx 将两个 Vue 项目分别配置为独立的 server，同时在两个 server 中都配置了 /tiles/ 静态资源映射，使其共享访问地图切片目录。

二、本地实现

2.1 本地环境

首先，环境准备。准备好地图切片文件，按照以下目录存放文件位置

your-project/
├── public/
├── src/
└── static-server/tiles/  ✅ 地图切片文件

图例：

然后使用一个静态服务器启动这个 tiles 文件夹。例如：http-server（Node 工具，简单开发用）。这里通过以下命令，安装服务到项目中：

npm install -g http-server

然后修改你 Cesium 加载切片的地址：

      // 1. 加载卫星图this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: 'http://localhost:9000/imagery/{z}/{x}/{y}.jpg',maximumLevel: 18,tilingScheme: new Cesium.WebMercatorTilingScheme(),credit: new Cesium.Credit("卫星图层"),}));// 2. 加载中文标签图（注意要透明 PNG）this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: 'http://localhost:9000/label/{z}/{x}/{y}.png',maximumLevel: 18,tilingScheme: new Cesium.WebMercatorTilingScheme(),credit: new Cesium.Credit("中文标注图层"),}));

离线地图切片文件，一般有自己的排序，使用 标准的 ZXY 目录结构 来加载瓦片。Cesium 加载地图切片时，是按需动态加载的，并不是一次性加载所有瓦片。它的加载遵循以下逻辑：

  1. 视野优先加载：根据相机（视角）当前的经纬度范围和缩放层级，只加载“可视区域”的瓦片；

  2. 层级递进加载：优先加载低层级（小分辨率），然后加载更细节的高层级瓦片；

  3. 懒加载 + 回收机制：当你移动视角或放大/缩小时，Cesium 会按需加载新瓦片，并可能回收视野外的瓦片以节省内存。

Cesium 使用 标准的 ZXY 目录结构 来加载瓦片：

  1. {z} → 层级（Level）从 0 开始，层级越高，分辨率越高，瓦片数量越多；

  2. {x} → 经度方向编号；

  3. {y} → 纬度方向编号（通常从左上角开始编号）；

关键部分：

url: 'http://localhost:9000/imagery/{z}/{x}/{y}.jpg',

url: 'http://localhost:9000/label/{z}/{x}/{y}.png',

代码修改完成之后，启用两个终端窗口，一个用来启用 http-server 服务，另一个用来启动项目，注意本地是跨域启动：

http-server ./static-server/tiles -p 9000 --cors

图例：

本地地图切片文件，加载成功。

2.2 具体实现

Cesium 前端具体的代码接入

2.2.1 初始配置

Cesium Viewer 初始化配置

this.viewer = new Cesium.Viewer(dom, {imageryProvider: false,baseLayerPicker: false,animation: false,vrButton: false,geocoder: false,timeline: false,sceneModePicker: false,navigationHelpButton: false,navigationInstructionsInitiallyVisible: false,infoBox: false,fullscreenButton: false,selectionIndicator: false,homeButton: false,scene3DOnly: true,
});this.viewer.cesiumWidget.creditContainer.style.display = "none";
2.2.2 加载切片

加载地图切片图层（关键）

// 加载卫星图层
this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: '/tiles/imagery/{z}/{x}/{y}.jpg',tilingScheme: new Cesium.WebMercatorTilingScheme(),maximumLevel: 18,})
);// 加载中文标注图层（需 PNG 透明底）
this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: '/tiles/label/{z}/{x}/{y}.png',tilingScheme: new Cesium.WebMercatorTilingScheme(),maximumLevel: 18,})
);
2.2.3 统一好处

使用统一路径的好处

  1. 所有请求均走 /tiles/...，不依赖 IP、端口、环境变量

  2. 本地开发可用 http-server 启动切片服务，线上部署用 Nginx

  3. 多项目共用一套地图资源，节省空间和维护成本

2.2.4 完整代码
    createCesiumViewer(dom) {this.viewer = new Cesium.Viewer(dom, {imageryProvider: false,baseLayerPicker: false,animation: false,vrButton: false,geocoder: false,timeline: false,sceneModePicker: false,navigationHelpButton: false,navigationInstructionsInitiallyVisible: false,infoBox: false,fullscreenButton: false,selectionIndicator: false,homeButton: false,scene3DOnly: true,});// 去掉 logothis.viewer.cesiumWidget.creditContainer.style.display = "none";// 1. 加载卫星图this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: 'http://localhost:9000/imagery/{z}/{x}/{y}.jpg',maximumLevel: 18,tilingScheme: new Cesium.WebMercatorTilingScheme(),credit: new Cesium.Credit("卫星图层"),}));// 2. 加载中文标签图（注意要透明 PNG）this.viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({url: 'http://localhost:9000/label/{z}/{x}/{y}.png',maximumLevel: 18,tilingScheme: new Cesium.WebMercatorTilingScheme(),credit: new Cesium.Credit("中文标注图层"),}));// // 现场实际部署// this.viewer.imageryLayers.addImageryProvider(//   new Cesium.UrlTemplateImageryProvider({//     url: '/tiles/imagery/{z}/{x}/{y}.jpg',//     tilingScheme: new Cesium.WebMercatorTilingScheme(),//     maximumLevel: 18,//   })// );// this.viewer.imageryLayers.addImageryProvider(//   new Cesium.UrlTemplateImageryProvider({//     url: '/tiles/label/{z}/{x}/{y}.png',//     tilingScheme: new Cesium.WebMercatorTilingScheme(),//     maximumLevel: 18,//   })// );this.$root.viewer = this.viewer;......},

这里本调试时，使用 http://localhost:9000/imagery/{z}/{x}/{y}.jpg' 路径，打包时候，使用 /tiles/imagery/{z}/{x}/{y}.jpg 路径，注意区分。

三、实际部署

Nginx 配置详解

这里实际部署时，是两个项目公用同一个地图切片，这样可以节省资源

2.1 端口 80 项目

system 项目（端口 80），nginx.conf

server {listen       80;server_name  localhost;location / {root   html/system;index  index.html index.htm;try_files $uri $uri/ /index.html;}location /tiles/ {root html;add_header Access-Control-Allow-Origin *;}location ^~/prod-api/ {proxy_pass http://localhost:8910/;}location = /iframeConfig {default_type application/json;return 200 '{"iframeUrl": "https://172.63.138.11/itrafficincident-hac/enterEvent"}';}error_page 500 502 503 504 /50x.html;location = /50x.html {root html;}
}

2.2 端口 81 项目

bigscreen 项目（端口 81），nginx.conf

server {listen       81;server_name  localhost;location / {root   html/bigscreen;index  index.html index.htm;try_files $uri $uri/ /index.html;}location /tiles/ {root html;add_header Access-Control-Allow-Origin *;}location ^~/dev-api/ {proxy_pass http://localhost:8910/;}error_page 500 502 503 504 /50x.html;location = /50x.html {root html;}
}

这里的配置文件，需要与你项目打包时，配置的代理保持一致。例如 80 端口项目中的 .env.production 配置的是 VUE_APP_BASE_API = '/prod-api' ，那么 nginx.conf 中的代理配置location ^~/prod-api/ 就需要保持同样，81端口项目同样。

2.3 路径说明

✅实际环境部署（重点）

部署时候不需要写死服务器 IP 和端口，只要你使用了相对路径（如 /tiles/imagery/{z}/{x}/{y}.jpg），并且：

  • 切片目录配置在了 与前端项目同一个 Nginx 服务下，

  • 切片请求路径 /tiles/ 映射到了切片实际目录（如 /var/www/tiles/），注意实际的路径位置（/usr/local/nginx/html/）。

那么 Cesium 会自动请求当前服务器的 /tiles/...，你完全不需要写死 IP 和端口。

✅相对路径能自动适配

当你用这种写法：

url: '/tiles/imagery/{z}/{x}/{y}.jpg'

在浏览器中运行时，Cesium 实际发出的请求地址为：

http://当前域名:当前端口/tiles/imagery/...

举例：

  • 项目部署在 http://192.168.1.100（或域名 map.mycompany.com）

  • 那么最终 Cesium 请求的地址是：

    http://192.168.1.100/tiles/imagery/4/10/5.jpg

这样你就避免了：

  • 写死 localhost:9000 ❌

  • 写死 192.168.x.x:8080 ❌

✅ 你只需要保证这两点：

项目配置说明
Nginx 配置/tiles/ 映射到实际磁盘路径（比如 /var/www/tiles/），注意实际的路径位置（/usr/local/nginx/html/）。
Vue 前端url: '/tiles/imagery/{z}/{x}/{y}.jpg'（使用相对路径）

tiles 路径解析说明

由于 root html; 的设定，访问地址：

http://your-server-ip:81/tiles/imagery/1/0/0.jpg

实际上对应的文件路径为：

/usr/local/nginx/html/tiles/imagery/1/0/0.jpg

2.4 其它配置

权限与跨域配置

  1. add_header Access-Control-Allow-Origin *; 用于避免 Cesium 的跨域错误

  2. /usr/local/nginx/html/tiles/ 目录需有读取权限，推荐 chmod -R 755 tiles

四、常见问题

常见问题排查与调试技巧

4.1 未加载地图层

未加载地图图层的常见原因

  1. ❌ 忘记使用 viewer.imageryLayers.addImageryProvider 挂载图层

  2. ❌ 使用了 new UrlTemplateImageryProvider() 却没有添加

  3. ✅ 正确方式是 this.viewer.imageryLayers.addImageryProvider(...)

4.2 调试建议

浏览器调试建议

  1. 打开 DevTools → Network → 过滤关键字 tiles/

  2. 看是否发出了请求、状态是否为 200

  3. 确保请求路径形如 /tiles/imagery/1/0/0.jpg

4.3 测试路径

访问测试路径

可手动测试以下 URL 确认服务是否 OK：

http://your-ip/tiles/imagery/0/0/0.jpg
http://your-ip:81/tiles/label/0/0/0.png

若返回 404，检查文件是否实际存在于服务器对应路径。

4.4 权限跨域

权限或跨域问题

  • 如果浏览器报 CORS 错误，检查 Access-Control-Allow-Origin 是否配置

  • 如果地图切片 403，检查文件权限（推荐 755）

五、注意事项

在使用 Vue 与 Cesium 集成离线地图切片资源的过程中，合理的配置与细节把控是确保地图正常加载和系统稳定运行的关键。以下是一些在实际开发与部署中必须注意的重要事项，涵盖路径配置、权限管理、前端调用等多个方面，帮助你规避常见问题，提升部署效率。

类别注意事项说明
切片路径地图切片目录（如 /tiles/）必须通过 Nginx 配置为静态资源目录，确保能以 URL 路径形式访问，例如：http://localhost/tiles/。路径结构应与切片命名规则一致（如 TMS 或 WMTS 标准）。
Vue 前端配置在 Cesium 中引用地图切片时，应使用相对路径 /tiles/...，避免将 IP 和端口写死在代码中，便于部署到不同环境（如测试、生产、内网等）。
多项目部署若部署了多个前端项目（如 bigscreen 和 system），每个项目的 Nginx server 配置中都应包含对 /tiles/ 的映射，确保两个系统都能访问到同一套地图资源。
权限设置地图切片文件所在物理路径（如 /usr/local/nginx/html/tiles/）必须赋予 Nginx 进程足够的读取权限，否则会导致 403 Forbidden 错误。可使用 chmod 和 chown 调整权限。
加载图层在 Cesium 中使用 imageryLayers.addImageryProvider() 方法加载离线地图图层，并根据实际切片格式选择合适的 Provider（如 WebMapTileServiceImageryProvider 或自定义 Provider）。必要时还需配置最大层级、tilingScheme 等参数。
本地测试开发阶段可用 http-server 快速启动一个临时服务用于测试地图加载效果，命令如下：<br>http-server ./static-server/tiles -p 9000 --cors<br>此方式支持跨域访问，方便前后端分离调试。

通过以上注意事项的合理配置与实践，可以有效避免因路径错误、权限不足或配置不统一导致的地图加载失败问题，保障多个 Vue 项目在内网或无网络环境下稳定地共用同一套离线地图资源，提升系统的整体健壮性与可维护性。

六、本文总结

通过本文的实践，我们可以非常清晰地完成一个目标：

在同一台服务器上，多个 Vue 项目通过统一配置的 /tiles/ 路径，共享使用离线地图切片资源，既节省存储资源，又利于统一管理。

实际项目中，只要掌握了正确的目录结构、Nginx 配置方式、前端使用路径的一致性，你就能非常稳定地搭建起高效可维护的 Cesium 离线地图环境。

如需多图层动态切换、夜景图叠加、不同地图源混合（天地图、高德、谷歌自定义切片等），也欢迎留言或继续深入交流。

七、更多操作

请看，GIS Develop 个人专栏

CesiumJShttps://blog.csdn.net/weixin_65793170/category_12356611.htmlhttps://blog.csdn.net/weixin_65793170/category_12356611.html

http://www.dtcms.com/a/278337.html

相关文章：

  • H264的帧内编码和帧间编码
  • 2025年睿抗机器人开发者大赛CAIP-编程技能赛本科组（省赛）解题报告 | 珂学家
  • Python 变量与简单输入输出：从零开始写你的第一个交互程序
  • 【Java入门到精通】（四）Java语法进阶
  • 动手学深度学习——线性回归的从零开始实现
  • 【记录】BLE｜百度的旧蓝牙随身音箱手机能配对不能连接、电脑能连接不能使用的解决思路（Wireshark捕获并分析手机蓝牙报文）
  • 1.2.2 高级特性详解——AI教你学Django
  • 【图片识别改名】水印相机拍的照片如何将照片的名字批量改为水印内容？图片识别改名的详细步骤和注意事项
  • 【WPF】WPF 自定义控件 实战详解，含命令实现
  • 【零基础入门unity游戏开发——unity3D篇】3D光源之——unity6的新功能Adaptive Probe Volumes（APV）（自适应探针体积）
  • ACL流量控制实验
  • 深入了解linux系统—— 进程信号的产生
  • 客户端主机宕机，服务端如何处理 TCP 连接？详解
  • EasyExcel实现Excel文件导入导出
  • VScode链接服务器一直卡在下载vscode服务器，无法连接成功
  • C++之哈希表的基本介绍以及其自我实现（开放定址法版本）
  • 多客户端 - 服务器结构-实操
  • 史上最清楚！读者，写者问题（操作系统os）
  • 基于 Gitlab、Jenkins与Jenkins分布式、SonarQube 、Nexus 的 CiCd 全流程打造
  • SQL创建三个表
  • 从 JSON 到 Python 对象：一次通透的序列化与反序列化之旅
  • Dubbo高阶难题：异步转同步调用链上全局透传参数的丢失问题
  • Selenium动态网页爬虫编写与解释
  • 【微信小程序】
  • 当你在 Git 本地提交后，因权限不足无法推送到服务端，若想撤销本次提交，可以根据不同的需求选择合适的方法，下面为你介绍两种常见方式。
  • 清除 Android 手机 SIM 卡数据的4 种简单方法
  • 云手机常见问题解析：解决延迟、掉线等困扰
  • 云手机的多重用途：从游戏挂机到办公自动化
  • kafka的部署
  • 从零实现浏览器摄像头控制与视频录制：基于原生 JavaScript 的完整指南