OpenLayers 6 主要 API 变化与迁移
OpenLayers 6.0.0 于 2019 年 9 月 26 日发布，到 6.15.1（2022 年 7 月）结束整个 6.x 系列，核心变化是渲染合成策略、View 约束、图层事件、瓦片坐标体系和部分废弃 API 全部调整，导致与 5.x 不兼容。迁移时必须改 View 选项（如 multiWorld、constrainOnlyCenter）、把 precompose/render 换成 prerender/postrender、按新 XYZ 规则重写自定义 tileUrlFunction，并用 VectorImage 替代旧矢量 renderMode。按官方升级笔记逐项改完后，用现代浏览器跑一遍地图交互与图层命中检测即可验收。
为什么这些 API 变化值得关注
OpenLayers 6 把图层从单一 Canvas 合成改成独立 DOM 元素叠加，支持 Canvas 与 WebGL 混合，内存占用更低，矢量瓦片渲染也更稳。代价是旧代码里大量假设“整图一张画布”的写法会失效。对 GIS 项目来说，最直接影响是：视图不再默认多世界、图层事件名变了、自定义瓦片加载器 y 坐标方向反了、declutter 变成跨图层统一处理。搞清楚这些，才能避免升级后地图“飞出去”、点击失效或瓦片错位。
- 渲染：图层独立元素，旧的 precompose/postcompose 全部换成 prerender/postrender。
- 视图：约束责任集中到 View，默认只显示一个世界。
- 矢量：renderMode: ‘image’ 移到独立的 VectorImage 图层。
- 瓦片：内部坐标改为标准 XYZ（y 向下增），自定义函数必须改。
若你还在纠结 OpenLayers 与其他库的选型，可先看本站的 Leaflet和OpenLayers选哪个?二者优劣对比?，再决定是否继续深耕 6.x 或直接跳更高版本。
主要向后不兼容变化一览
下面表格只列最常踩坑的几项（完整列表以官方升级笔记为准）。截至 2026 年 11 月，这些规则对仍停留在 6.x 的项目依然有效。
| 变化项 | 旧写法 / 行为 | 新写法 / 行为 | 迁移动作 |
|---|---|---|---|
| 图层事件 | precompose / render / postcompose | prerender / postrender | 改事件名；需要即时矢量绘制时用 getVectorContext() |
| View 约束 | setCenter 等可绕过；extent 只约束中心；默认多世界 | 全部走约束；extent 约束整个视口；默认单世界 | 加 multiWorld: true 或 constrainOnlyCenter: true 恢复旧行为 |
| 矢量渲染模式 | Vector 图层 renderMode: ‘image’ | 改用 ol/layer/VectorImage + Vector 源 | 新建 VectorImage 图层替换 |
| 瓦片坐标 | y 向上（负值） | y 向下（标准 XYZ） | 自定义 tileUrlFunction 里 y = tileCoord[2]（去掉取反） |
| forEachLayerAtPixel | 可靠按图层命中 | 可能假阳性（图层有时合到同一 canvas） | 给每个图层设不同 className；或改用 6.13+ 的 layer.getData(pixel) |
| declutter | 单图层内处理 | 跨所有 Vector/VectorTile 统一，高 zIndex 优先，图层内顺序反转 | 重新调 zIndex；注意图像/文本会盖在多边形上方 |
| 图层归属 | 同一图层可挂多地图 | 只能加到一张地图 | OverviewMap 必须单独提供图层列表 |
更多细节可直接对照 官方 upgrade-notes.md 和 v6.0.0 发布说明。
可执行迁移步骤
按下面顺序改，改完一项就跑一次地图，别一口气全换。
- 锁定版本：npm install ol@6.15.1（或 package.json 写死 “ol”: “6.15.1”）。模块导入保持 import Map from ‘ol/Map’ 等形式。
- 改 View：检查 constructor 选项。需要旧多世界行为就加 multiWorld: true；需要只约束中心就加 constrainOnlyCenter: true。把 rotate 改成 adjustRotation（传 delta）。constrainResolution 只留给 View，交互里的对应选项删掉。
- 换图层事件：所有 map.on(‘precompose’…) 等改成图层或 map 的 ‘prerender’/’postrender’。需要画临时矢量时从 ‘ol/render’ 引入 getVectorContext，在事件回调里创建 context。
- 处理矢量图层：把带 renderMode: ‘image’ 的 Vector 换成 VectorImage。declutter 相关逻辑按新跨图层规则重新测一遍。
- 修自定义瓦片：tileUrlFunction / tileLoadFunction 里把旧的 y = -tileCoord[2] – 1 改成 y = tileCoord[2]。WMTS 的 sizes 高度符号也核对一下。VectorTile 的 loader 现在直接收 (extent, resolution, projection)，传给 format.readFeatures 即可，不再调 setProjection/setExtent。
- 其他清理：ol/has 的 TOUCH/GEOLOCATION 常量删掉，改用原生检测；打印样式自己加 @media print { .ol-control { display: none; } }；getGetFeatureInfoUrl 改名 getFeatureInfoUrl；getFeaturesAtPixel 永远返回数组（空则 []）。
- OverviewMap 和 Graticule：OverviewMap 构造时必须传 layers 数组；ol/Graticule 换成 ol/layer/Graticule。
图层点击与坐标拾取逻辑若因事件名或命中检测变化而失效，可对照本站 OpenLayers点击事件：图层点击事件和坐标拾取 里的写法重新接一遍。
迁移坑位与验收标准
改完代码后别急着上线，用下面标准自测：
- 视图：低缩放时是否还出现多个世界？拖到边缘是否还能继续平移？不符合预期就检查 multiWorld / constrainOnlyCenter。
- 图层命中：forEachLayerAtPixel 或 getFeaturesAtPixel 是否出现假阳性？给图层加不同 className 再测；6.13 起优先用 layer.getData(pixel)。
- 瓦片：自定义底图或矢量瓦片是否错位、空白？重点查 y 坐标方向。
- 性能：多张 Image 图层时内存是否暴涨（尤其移动端）？官方确认 Image 图层独立 canvas 是已知问题，尽量改瓦片或减少数量。
- declutter：文本/图标是否按预期避让？高 zIndex 图层是否盖住了低的？矢量图层内图像是否跑到多边形上面？
- 内存：地图销毁时调用 map.setTarget(null)，避免早期版本遗留的泄漏。
涉及矢量点聚合时，declutter 新规则会影响显示顺序，可参考本站 OpenLayers点聚合怎么实现?代码逻辑是什么? 里的聚合思路，把 zIndex 和 declutter 一起调。
浏览器要求：现代浏览器（Chrome、Firefox、Safari、Edge）即可；若还要支持 IE9+ 或老 Android，需 Babel 转译并补 polyfill（fetch、requestAnimationFrame、classList 等）。TypeScript 用户从 6.6 起包内自带声明，遇到冲突可设 skipLibCheck: true。
常见问题
升级后 forEachLayerAtPixel 经常命中错误图层怎么办？
因为新渲染策略下多个图层有时会画到同一 canvas，产生假阳性。给每个图层设置互不相同的 className，或改用 6.13 引入的 layer.getData(pixel) 按图层取像素数据。
自定义瓦片突然全部 404 或错位？
内部瓦片坐标 y 方向改成了向下增加。把旧的 y = -tileCoord[2] – 1 改成 y = tileCoord[2]，同时检查 WMTS sizes 数组的高度符号是否需要同步调整。
矢量图层的 image 渲染模式找不到了？
renderMode: ‘image’ 已从 Vector 图层移除，改用新的 ol/layer/VectorImage 搭配 ol/source/Vector。VectorTile 的 ‘vector’ 模式也删了，只剩 hybrid（默认）和 image。
OverviewMap 报错或空白？
图层现在只能属于一张地图，OverviewMap 必须在构造时显式传入自己的 layers 数组，不能再共享主图图层。
OpenLayers 6 的迁移核心就是“渲染独立化 + 约束集中化 + 坐标标准化”。先按表格改 View、事件和瓦片函数，再按验收清单逐项测交互与命中，通常一天内就能跑通。建议锁定 6.15.1 完成迁移后再考虑是否继续升到 7/8/9；遇到官方示例与本地行为不一致时，以 upgrade-notes 为准，逐步回退选项验证。