首页 / Cesium / API 文档
Terrain
先看结论
地形包装器：把异步获取的地形服务包成一个对象，交给场景使用。
1.104 之后替代了直接给 terrainProvider 赋值的旧写法。
new Cesium.Terrain(terrainProviderPromise)
构造参数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
terrainProviderPromise | Promise<TerrainProvider> | 必填 | 地形服务的异步结果，如 CesiumTerrainProvider.fromUrl(...) |
常用成员与方法
| 成员 | 类型 / 返回 | 说明 |
|---|---|---|
provider | TerrainProvider | 解析后的地形服务，Promise 完成前为 undefined |
Terrain.fromWorldTerrain(options) | Terrain | 使用 Cesium World Terrain，需 ion 令牌 |
options.requestVertexNormals | boolean | 请求法线，地形光照需要 |
options.requestWaterMask | boolean | 请求水面遮罩，用于水面反光 |
示例
// 自建地形服务：URL 里带瓦片层级占位
var terrain = new Cesium.Terrain(
Cesium.CesiumTerrainProvider.fromUrl(
'https://terrain.example.com/terrain/{z}/{x}/{y}.terrain?v=1.2.0',
{
requestVertexNormals: true,
requestWaterMask: true
}
)
);
// 方式一：创建后设置
viewer.scene.setTerrain(terrain);
// 方式二：写进 Viewer 参数（此时不要再调 setTerrain）
// var viewer = new Cesium.Viewer('map', { terrain: terrain });
// 地形就绪后读取某点高度
terrain.provider.readyPromise.then(function () {
var h = viewer.scene.globe.getHeight(
Cesium.Cartographic.fromDegrees(116.391, 39.907)
);
console.log('地形高度', h);
});注意事项
new Cesium.Terrain(...)立即返回，内部仍在等 Promise；provider在就绪前不可用。scene.globe.terrainProvider是只读的，运行时换地形只能用scene.setTerrain。- 请求法线与水面遮罩会显著增加瓦片体积与首次加载时间，只做数据展示时可以不开启。
- 地形就绪前
globe.getHeight返回 undefined，贴地要素会先落在椭球面上再被抬高。
经纬志（2026）。《Terrain》。https://www.jingweizhi.com/cesium/api/terrain.html（访问日期 2026-11-03）。