配置参数与版本依赖问题

约 1036 字大约 3 分钟

2026-10-28

config.json 中自定义 crs 后为何天地图无法加载

回复无法加载。底层不支持多坐标系图层叠加，只能叠加相同坐标系的图层。

图层 attr 中的 name 属性取不出来怎么办

回复先把取到的 attr 转为 json 格式，再进行属性操作。

config.json 中配置 classificationType 报错

回复Cesium.ClassificationType.CESIUM_3D_TILE 是数字枚举，在配置文件中应写对应的数值，而不是枚举名。回复不支持这种绑定方式。可在 map 构造完成后，通过 getLayer 获取对应图层，再用代码设置 popup。

打开图层控件后列表为空

回复需按需传入 layers 参数；若 basemaps 也为空，还需关闭默认的底图切换控件。

getBasemaps 为何返回空数组

回复需关闭 Cesium 底图控制控件，未关闭时走的是原生 Cesium 那套规则，导致 getBasemaps 取不到值。

config.json 中如何配置 billboardEntity

回复在 config 中按 symbol 配置的书写方式配置即可。

哪些场景参数会显著影响 FPS

回复以下参数会直接影响 FPS，建议修改：

"showSkyAtmosphere": false,
"fog": false,
"fxaa": false,
"globe": { "showGroundAtmosphere": false }

以下为可选修改项，建议对比 FPS 变化后决定：

"scene3DOnly": true   // 不用 2D 时建议 true

如何将地图背景设置为透明

回复Cesium 背景色本身不支持透明度，必须在 Map 初始化时传入：

scene: { contextOptions: { webgl: { alpha: true } } }

之后再设置 backgroundColor 为 transparent 才会生效。

如何隐藏月亮、太阳与天空盒等场景元素

回复可通过以下场景参数控制，将 showSun、showMoon、showSkyBox、showSkyAtmosphere 等按需设置为 false 即可隐藏对应元素：

shadows: false,          // 是否启用日照阴影
removeDblClick: true,    // 是否移除 Cesium 默认双击事件
showSun: true,
showMoon: true,
showSkyBox: true,
showSkyAtmosphere: true,
fog: true,
fxaa: true

如何关闭拖拽地图后的惯性滑行

map.scene.screenSpaceCameraController.inertiaSpin = 0
map.scene.screenSpaceCameraController.inertiaTranslate = 0

更新 mars3d 主库后插件版本是否需要同步

回复需要同步。插件版本必须与 Mars3D 版本保持一致，避免冲突。

mars3d 与 mars3d-cesium 是什么关系

回复二者版本基本一对一，微调后版本号会加 0.1，且只能选择其中一个 Cesium。注意：yarn 安装 mars3d 已不再包含 mars3d-cesium，需单独安装并引入样式：

import "mars3d-cesium/Build/Cesium/Widgets/widgets.css"

如何锁定 mars3d 相关依赖版本

回复package.json 中不要写 ^ 号，写死版本号（如 "mars3d-cesium": "1.91.0"），然后删除 node_modules 重新 npm install。

如何获取 mars3d 历史版本

回复npm 项目修改 package.json 中的版本号后重新安装。静态引入方式可从 registry.npmjs.org/mars3d/-/mars3d-x.y.z.tgz 下载对应版本包，或从 jsDelivr 获取。

官网 SDK 与 npm 版本不一致怎么办

回复npm 渠道的版本需要等正式发布后才会同步更新，存在滞后；而官网提供的离线 SDK 包始终跟随最新代码，已修复 npm 旧版本中的已知问题。因此当两者版本不一致、或你需要立即使用最新修复时，可以直接从官网下载最新 SDK。

操作步骤：

打开官网「开发教程 → 介绍SDK」页面，点击「离线下载SDK包」按钮获取最新的 SDK 压缩包（该入口在常用资源地址中也有收录）。
npm 方式的项目：解压后将包内对应的 mars3d 库目录覆盖项目中的 node_modules/mars3d。注意：这种覆盖是临时的，重新执行 npm install 后会被 npm 上的版本回退覆盖，建议同时锁定 package.json 版本、并在团队内统一做法。
静态引入方式的项目：直接用 SDK 包中的 lib/mars3d 目录替换项目内引用的旧目录即可，替换后刷新浏览器确认生效。
如需了解具体版本间的变更内容，可对照版本更新日志确认修复范围。