强制使用WebGL2，MapLibre GL JS v6.0 发布！

2026 年 7 月 22 日，开源矢量地图引擎 MapLibre GL JS 正式发布 v6.0.0。这不是小修小补，最明显的变化有两条，一是必须 WebGL2，二是发行包只剩 ESM。对还在用 CDN 加载单个 maplibre-gl.js、或者还在给老浏览器兼容 WebGL1 的项目，小编建议这次升级需要认真评估。

为什么强制 WebGL2

官方说法是 WebGL2 已经普及且 WebGL1 用户很少，继续双栈维护不划算。对业务侧来说，地图 API 用法大体不变，现代浏览器基本没问题（可参考 Can I use WebGL2），极老设备、被策略禁用 GPU、或只剩软件渲染的环境可能直接起不来图；没有 WebGL 时，现在可以通过 .on("error") 接到相关错误，比以前更好排查。小编建议升级前先统计下目标用户的浏览器版本，尤其是政企内网、老 Win、定制浏览器这些场景。

ESM-only：UMD 时代结束了

v6 只发布 ESM 包，主文件变成 maplibre-gl.mjs（外加 worker）。以前的 UMD 包 maplibre-gl.js、以及单独的 CSP 构建，都不再提供。npm 默认导入要从 import maplibregl from 'maplibre-gl' 改成 import * as maplibregl from 'maplibre-gl'，或直接具名导入 Map；CDN 则要把原来的 <script src="...maplibre-gl.js"> 换成 <script type="module"> 再 import。用 Vite / webpack / esbuild 打包时，仍可能要做一次 setWorkerUrl()，纯浏览器从 CDN 拉 ESM 时 worker 一般会自动探测；跨域 CDN 场景通常还要允许 worker-src 里的 blob:。简单说，这次的版本不是换个版本号，若还在用很老的无模块页面模板，需要修改加载方式，对于老项目来说是个不小的工作量。

其他非兼容性变更

除了 WebGL2 和 ESM，下面这些与之前版本不兼容的更新也值得关注。

1. styleimagemissing 不再通过事件回调补图，需改用 Map.setMissingStyleImageResolver，支持同步或异步。
2. Map 改为组合 Camera，不再提供内部的 map.transform，请优先使用公开 API。
3. 地图事件全面类化，类型约束更严；不建议再用 instanceof 判断，应依据 type 字段区分。
4. 着色器中的 #pragma mapbox 需改为 #pragma maplibre。
5. GeoJSONSource.setData 移除了第二个参数 waitForCompletion，也不再链式返回 this。
6. zoomLevelsToOverscale 默认值改为 4，密集注记在高缩放时更友好，但 queryRenderedFeatures 与 v5 略有差异。
7. TypeScript 编译目标升至 ES2022。
8. GeoJSON 嵌套对象属性的编解码行为有调整，相关属性读写建议重新核对。

功能与性能增强

除非兼容性变更外，v6 也带来一批能力与性能改进。

1. 新增 fill-layer-opacity、line-layer-opacity，支持整层统一透明，并改善透明线重叠时的伪影。
2. 地形渲染性能优化，包括共享 FBO、减少无效 DEM 查找、复用纹理等。
3. Feature State 内部结构优化，特定场景约有 3.4 倍加速。
4. 非 2 的幂次尺寸栅格瓦片也可使用 mipmap，高俯仰角下锯齿有所改善。

另外Bug 修复也较多，例如 worker 请求中止后的内存泄漏、flyTo 在 minZoom 下跳变、globe 与地形低俯仰拖拽跳变、休眠唤醒后 framebuffer 报错等。

总结 & 升级建议

新项目、且以现代浏览器为主，可直接采用 v6，减少后续迁移成本。如果需要升级的老项目且浏览器版本没有问题，可在测试环境按迁移指南调整导入与 worker，重点回归后再上线；若仍需兼容极老终端，或短期无法改造的项目，可暂时锁住 v5 版本。总体来说，v6 选择放弃旧平台兼容，把渲染与工程基线抬到 2022 年以后的 Web 平台，是一个不小的改动。按小编的经验，这么大的版本变更，只要项目能跑就先别动了...

如果你已经在业务里试过 v6，踩过坑或有现成迁移片段，欢迎留言补充。