首页 / MapLibre / API 文档
removeLayer
先看结论
从样式里移除图层，连同它的绘制资源一起释放；源不会自动被删。
map.removeLayer('layer-id')
行为
| 情况 | 结果 |
|---|---|
| 图层存在 | 从渲染顺序中移除，资源可被回收 |
| id 不存在 | 触发 error 事件：Cannot remove non-existing layer "…" |
| 样式尚未加载 | 触发 error 事件，提示样式未就绪 |
| 源仍被其他图层使用 | 不受影响；只有 removeSource 会检查引用 |
相关成员
| 成员 | 说明 |
|---|---|
map.getLayer(id) | 返回图层对象，不存在则为 undefined |
map.moveLayer(id, beforeId?) | 调整叠放顺序，不做删除 |
map.removeSource(id) | 删除数据源，仍被图层引用时报错 |
setLayoutProperty(…, 'visibility', 'none') | 隐藏但保留图层 |
示例
function removeIfExists(id) {
if (map.getLayer(id)) {
map.removeLayer(id);
return true;
}
return false;
}
/* 删除图层后，确认没有别的图层用这个源，再删源 */
removeIfExists('city-halo');
removeIfExists('city-dots');
if (map.getSource('cities') && !map.getStyle().layers.some(function (l) {
return l.source === 'cities';
})) {
map.removeSource('cities');
}
map.on('error', function (e) {
console.warn('样式操作失败：' + (e.error && e.error.message));
});注意事项
removeSource 不会检查引用关系，先删源再删图层时，
图层仍在渲染但拿不到数据，控制台会出现一串瓦片读取错误。
顺序固定为：先删图层，再删源。
频繁删除又重建同一图层会反复编译着色器，缩放时出现卡顿。
只是周期性隐藏时用 visibility，把删除留给真正不再需要的图层。
删除不会撤销样式里的定义。样式文件里写死的图层被删掉后，
setStyle 重新加载同样的样式，它会再次出现。
经纬志（2026）。《removeLayer》。https://www.jingweizhi.com/maplibre/api/remove-layer.html（访问日期 2026-11-03）。