首页 / Cesium / API 文档

Model

先看结论

单个 glTF 模型的渲染对象。设备、车辆、风机、构件用它；城市级数据不要用它，那是 3D Tiles 的活。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-27 · 引用本文

两种加载方式

Cesium.Model.fromGltfAsync({ url, scale, ... }) → Promise<Model>

挂到 primitives 上，适合需要读取节点、材质、做动画控制的场景。

entity.model = new Cesium.ModelGraphics({ uri, scale, ... })

挂到实体上，跟随实体位置与朝向，适合大量同质模型。

参数

参数	默认	说明
`url` / `uri`	—	glTF 或 glb 地址
`scale`	1	缩放倍数。glTF 单位是米，模型按真实尺寸建模时保持 1
`minimumPixelSize`	0	最小屏幕尺寸，远景时模型自动放大到该像素，避免消失
`maximumScale`	—	配合上一项限制最大放大倍数，防止远看成一个大方块
`heightReference`	NONE	贴地或相对地面
`color`	WHITE	叠加色，与 `colorBlendMode` 配合
`colorBlendMode`	HIGHLIGHT	HIGHLIGHT 高亮 / REPLACE 替换 / MIX 混合
`colorBlendAmount`	0.5	MIX 模式下的混合比例
`clippingPlanes`	—	局部裁剪平面集合
`silhouetteColor` / `silhouetteSize`	—	轮廓描边，做选中效果
`shadows`	DISABLED	投影模式
`runAnimations`	true	是否播放模型自带动画
`clampAnimations`	true	动画结束后停在最后一帧
`incrementallyLoadTextures`	true	先出白模再贴纹理，大纹理模型首屏更快
`upAxis` / `forwardAxis`	Y / Z	模型坐标轴约定，姿态不对时调这里

var model = await Cesium.Model.fromGltfAsync({
  url: '/models/pump.glb',
  scale: 1.0,
  minimumPixelSize: 48,
  maximumScale: 200,
  color: Cesium.Color.fromCssColorString('#4d9bff'),
  colorBlendMode: Cesium.ColorBlendMode.HIGHLIGHT,
  colorBlendAmount: 0.4
});

model.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(
  Cesium.Cartesian3.fromDegrees(116.391263, 39.907359, 30)
);
viewer.scene.primitives.add(model);

eastNorthUpToFixedFrame 生成以该点为原点、Z 轴朝上的局部矩阵。直接用模型自己的矩阵而不套这一层，模型会躺倒或者埋在地心方向。

常用成员

成员	说明
`model.readyPromise`	旧写法下的加载完成信号
`model.boundingSphere`	包围球，用于定位相机
`model.activeAnimations`	动画集合，可 `add` 指定片段与循环次数
`model.getNode(name)`	取节点，改它的变换矩阵
`model.getMaterial(name)`	取材质，改颜色或贴图
`model.color` / `colorBlendMode`	运行时改高亮状态
`model.show`	整体显隐
`model.destroy()`	释放 GPU 资源

// 只播放名为 "rotate" 的动画，循环 3 次
model.activeAnimations.add({
  name: 'rotate',
  loop: Cesium.ModelAnimationLoop.REPEAT,
  repetitions: 3,
  speedup: 1.5
});

排查：模型发黑

模型出来是一团黑，九成是因为场景没有光照。glTF 的 PBR 材质需要光源，关掉太阳之后只剩环境光：

viewer.scene.globe.enableLighting = true;   // 地形与模型受太阳照射
viewer.scene.light = new Cesium.DirectionalLight({
  direction: new Cesium.Cartesian3(1, 0, 0)
});

另一种原因是材质本身是金属度 1、粗糙度 0 的 PBR 材质，没有环境贴图时反射不到东西，看起来也是黑的。这种情况需要调整建模导出参数，或者给 scene.environmentMap 指定环境贴图。

排查：比例和位置不对

现象	原因
模型巨大，占满屏幕	建模单位是厘米（1 单位 = 1 厘米），导出时未换算，需把 `scale` 设为 0.01
模型躺倒	建模软件是 Z 轴朝上，glTF 约定 Y 轴朝上，导出时需转换或改 `upAxis`
模型悬空或埋地	模型原点不在底部中心，需要用节点偏移对齐，不要靠改高度硬凑
纹理丢失	glb 里没打包贴图，或贴图路径是绝对路径

数量上限。每个 Model 是一次独立的绘制调用，几百个之后帧率明显下降。同一种模型重复出现时，用 Cesium.ModelInstanceCollection 或 3D Tiles 的实例化扩展，一次绘制上千个。

引用本文

经纬志（2026）。《Model》。https://www.jingweizhi.com/cesium/api/model.html（访问日期 2026-11-03）。