外观
集成与部署报错排查
约 721 字大约 2 分钟
2026-10-28
集成报错的通用排查四步法
回复按顺序排查，可覆盖绝大多数集成期报障：- 看 node 版本，需 14 或 16 以上，过低先升级；
- 看依赖安装方式，是否用 cnpm 安装，建议改用 npm 或 yarn，并切换淘宝镜像源；
- 看
CESIUM_BASE_URL与 Cesium 主目录配置是否正确； - 看 mars3d 与 mars3d-cesium 版本是否冲突。
集成前的环境准备要求
回复node 需 14 以上。不建议使用 cnpm，可能出现 rimraf 报错或安装异常。浏览器需支持 ES7 以上语法。提示 Cesium 主目录未找到
回复报错常表现为 undefined。需配置CESIUM_BASE_URL，参考开发教程的集成章节。报错 Cesium is not defined
回复可按如下方式从 mars3d 上获取 Cesium 对象：const Cesium = mars3d.Cesium报错 EchartsLayer is not a constructor
回复缺少插件，需引入 mars3d-echarts。计算面积时报 graphic undefined
回复缺少 turf 库，引入后即可。老浏览器报不支持 ES7 语法错误
回复报错源于可选链a?.b 等新语法。升级浏览器即可，实际项目编译后不存在该问题。若无法升级浏览器，可将代码改写为 if (a) a.b 形式。Vue2 项目集成报错如何处理
回复建议在 index.html 中直接引入 Cesium：<script>window.CESIUM_BASE_URL = "<%=BASE_URL%>lib/Cesium/"</script>
<link rel="stylesheet" href="<%=BASE_URL%>lib/Cesium/Widgets/widgets.css" />
<script src="<%=BASE_URL%>lib/Cesium/Cesium.js"></script>vite 项目集成缺少插件
回复需配置 vite-plugin-mars3d。打包后静态资源路径错误（404）
回复修改静态资源路径配置为实际部署路径。另一种常见情况是打包后未部署到服务器，导致资源 404。IIS 部署时提示文件缺失
回复加载倾斜摄影时提示文件缺失，多为 IIS 未配置 mimetype（MIME 类型映射）。加载 glb 模型提示跨域
回复这是浏览器安全机制所致，使用官方推荐的 nginx 配置即可（已包含跨域响应头）。代码检查报"不允许空白函数"
回复代码检查（lint）规则要求函数体内不能全空，写个注释即可。切片底图显示正常但控制台持续报 404
回复原因是数据只切了所需区域的瓦片，地球其他区域无数据。可用 nginx 兜底：if ( !-f $request_filename ) {
rewrite (.*) /404.png;
}其中 404.png 放在 html 目录下，建议使用 1 像素纯透明图，兼顾视觉与性能。
nginx 因配置文件 BOM 无法启动
回复官方 nginx 包中conf/host/localhost_80.conf 的编码为 UTF-8 BOM，导致配置解析失败，转为 UTF-8 无 BOM 编码即可。项目打包体积超过 10M 如何优化
回复webpack 配置splitChunks 分包，或将 mars3d 与 mars3d-cesium 配置为 CDN 资源引入。