网上讲 Openlayers 遮罩效果的文章其实不少，但大部分都会停在最基础的那一版：先画一个半透明黑色矩形盖住全图，然后用 Canvas 的 globalCompositeOperation 挖出一个洞，把高亮区域露出来。这个思路没问题，第一篇文章里我也按这个路子把基础功能跑通了。但如果你真的拿它去做正式项目，很快就会碰到三个绕不开的问题：第一，业务上要高亮的区域往往不止一个，两个、五个、十几个点同时要“露出来”，代码该怎么组织？第二，遮罩的范围是动态变化的，用户点一下地图，洞口就要跟着变，总不能每次把整张地图重新渲染一遍吧？第三，遮罩画完以后，地图拖动、缩放的过程中边界很容易出现残影、偏移，这个问题在 OpenLayers 4 里尤为典型。
这篇文章就是来把这些问题一次性解决的。我会先讲清楚 Canvas 遮罩的底层原理，再给出一个适合多区域、可动态更新的完整实现，最后把拖动残影、坐标转换精度这些坑一条条列给你看。不管你是刚把第一个遮罩demo跑通的新手，还是已经写了好几个 OL 项目但没深挖过 Canvas 渲染细节的开发者，这份内容都能直接抄到你的项目里用.
1. 整体设计思路：从单区域到多区域遮罩
1.1 为什么第一篇的基础写法撑不住“多区域”需求
先回顾一下第一篇最核心的代码形态。通常是在地图的 postcompose 事件里拿到 Canvas 上下文，然后分两步操作：第一步，用 fillRect 把整个画布填成半透明黑色；第二步，把 globalCompositeOperation 改成 destination-out，再把目标区域画一遍，于是这个区域就变成了全透明，下面的地图也就显示出来了。
这个写法在单区域场景下非常清晰，但一旦目标变成“同时高亮上海市所有核心商圈”，问题就出来了。你会发现每个商圈都需要一组经纬度坐标，还需要不同的半径或者形状，如果还是每次都在事件回调里临时拼路径，代码很快就变成一坨难以维护的 if-else。更麻烦的是，只要地图有任何一次平移或者缩放，postcompose 就会触发一次，所有区域都得重新计算一遍，性能压力会随着区域数量成倍增加。
所以第二篇文章的核心思路，就是从“一次绘制”升级成“数据驱动绘制”。把所有需要高亮的区域，统一抽象成一张“区域配置表”，每一个配置项里记录坐标、类型、半径、颜色、透明度这些参数。渲染函数只负责遍历这张表，用统一的方式把每个区域画出来。
1.2 一个合理的数据结构长什么样
在实际项目里，我建议直接把遮罩配置设计成一个数组，每个元素代表一个高亮区域。这样做的好处有几个：一是和后端返回的数据结构天然对齐，后端接口返回一个 list，前端直接塞给渲染函数就行；二是便于动态新增和删除，不用动渲染逻辑，只改数组。
下面是我在项目里用的一个简化版结构：
var highlightRegions = [ { id: 'region_001', type: 'circle', // 区域类型：circle 圆形，polygon 多边形 center: [121.4737, 31.2304], // 中心点经纬度 radius: 3000, // 圆的半径，单位米，只对 circle 类型生效 fillColor: 'rgba(0, 0, 0, 0.6)', // 遮罩填充色 holeColor: 'rgba(255, 255, 255, 1)' // 挖洞区域画色，实际用透明混合 }, { id: 'region_002', type: 'polygon', coordinates: [ // 多边形顶点经纬度数组 [121.40, 31.20], [121.50, 31.20], [121.50, 31.28], [121.40, 31.28] ], fillColor: 'rgba(0, 0, 0, 0.6)' } ];你没看错，我把“遮罩颜色”放在每个区域配置里，而不是全局统一。因为实际业务里很可能需要不同区域使用不同的遮罩透明度，比如核心区域遮罩淡一点，周边区域遮罩浓一点，用来体现等级差异。当然，你也可以把 fillColor 抽到全局，只有 coordinates 跟 type 放在区域配置里，这个看具体项目。
1.3 渲染流程拆成三个独立环节
多区域遮罩的渲染流程，我强烈建议拆成三个独立环节：清理画布、绘制遮罩层、挖洞。三个阶段各干各的事，互不干扰。这样拆开以后，你后续做动态更新就非常轻松了，只需要在数据变化时重新执行一次这三个环节即可。
这里有一个容易被忽略的细节：地图的 postcompose 事件在每一帧渲染时都会触发，包括拖动、缩放、甚至只是鼠标滑过某些控件导致的重绘。所以这三个环节的执行频率其实很高。如果阶段二和阶段三里面用到的 Canvas 对象本身不做复用，每次都 new 一遍，性能损耗就会非常明显。正确的做法是提前创建一个离屏 Canvas，把遮罩层和挖洞结果缓存成一张静态图片，地图重绘时只需要把这张缓存图片贴上去。
2. 核心实现原理：Canvas“整面遮盖+挖洞”到底怎么运作
2.1 globalCompositeOperation 的两种关键模式
要理解遮罩，必须清楚 Canvas 的合成模式。这里只讲两个最关键的值，其他的有兴趣自己翻文档。
第一个是默认的 source-over。这个模式下，新画的图形会覆盖在原有内容之上。如果你直接用 fillRect 画一个半透明黑色矩形，它会盖住地图，这不是我们要的效果吗？确实是第一步要的效果，但第二步就麻烦了：如果用 source-over 去画高亮区域的圆，它只会让那个圆看起来更黑，而不会把遮罩层“擦掉”。
第二个就是 destination-out，这个模式的作用是“让新画的图形区域内的原有内容变成透明”。你可以把它理解成橡皮擦，只不过橡皮擦的形状由你画的路径决定。我们要实现“高亮区域显示地图”，本质就是先把整张地图用半透明黑色盖住，再用 destination-out 模式把高亮区域那一块的黑色擦掉，让下面的地图露出来。两步配合，一个标准的遮罩效果就出来了。
这里必须提醒你一点：destination-out 擦除的是 Canvas 上已有的像素，所以你不能在第一次 fillRect 之前就开启这个模式。如果顺序反了，你会把原本清晰的地图底图给擦掉，出现一个大白洞，而且这个白洞会一直透到地图底层容器去。
2.2 坐标转换是大多数坑的源头
Canvas 的绘制坐标是像素，而业务数据通常是经纬度。所以绘制之前，必须把经纬度转换成屏幕像素坐标。OpenLayers 4 里最常用的方法是 map.getPixelFromCoordinate(coordinate)，这个方法会返回一个 [x, y] 像素坐标，x 相对于地图容器左上角，y 往下为正。拿到像素坐标以后，你才能调用 ctx.arc(x, y, radius, 0, Math.PI * 2) 去画圆形的“洞”。
这里有个很容易踩的坑：圆形的 radius 是像素半径，不是地理半径。假设后端告诉你某个商圈要高亮周边 3000 米，你不能直接把 3000 当成像素值传给 ctx.arc。因为这会导致在缩放级别不同的时候，这个圆的实际地理范围完全不一样。在 Zoom 级别高的时候一个 3000 像素的圆可能覆盖大半个屏幕，在 Zoom 级别低的时候它可能小得看不见。
所以在绘制圆形遮罩之前，你得先做一次单位换算。OpenLayers 提供了简单的方式，可以取当前地图分辨率 map.getView().getResolution()，这个值的单位是“米/像素”。你用 3000 除以它，就得到对应像素半径。代码如下：
var view = map.getView(); var resolution = view.getResolution(); var pixelRadius = 3000 / resolution;当然，这个换算方式在 Web Mercator 投影下是比较准的，因为 Web Mercator 在赤道附近近似等距，纬度越高，形变越大。如果你的精度要求很高，或者业务区域跨越的纬度范围很大，建议用 ol.proj 的接口做更严格的距离换算，或者直接用 spherical 几何计算。考虑到大部分业务都在城市尺度，3000 米这种半径用上面的公式完全够用。
2.3 多区域的绘制顺序与重叠规则
多区域遮罩，尤其是两个区域靠得非常近时，会出现洞口重叠。如果第二次画路径时忘了重置合成模式，重叠部分可能反复被擦除，最终结果看起来会是：两个区域中心特别“亮白”，边界地带却出现了半透明残留。这在视觉上非常突兀。
解决方式有两个思路。思路一：先在一个离屏 Canvas 上把所有的区域路径全部收集起来，统一填充成一个完整的大路径，然后再一次性交给 destination-out 去挖。思路二：按照顺序依次绘制每个区域，但每个区域绘制前都显式地重置一遍合成模式，画完以后再切回 destination-out。
第二个思路代码上会更简单，但性能上不如第一个。因为每切换一次合成模式，Canvas 引擎都可能要做一次内部状态刷新。我在实际项目里用的是“合并路径”的做法，也就是用 ctx.beginPath() 开始，然后循环遍历每个区域，用 moveTo/lineTo 或者 arc 把路径都加进去，最后统一调用一次 fill()。这样无论多少个区域，挖洞的 fill 只执行一次，效率高很多，也彻底避免了重叠区域的二次擦除问题。
3. 完整实操：多区域动态遮罩的代码落地
3.1 基础工程结构准备
动手之前，先确认你本地的 OpenLayers 是 4.6.x 这个系列版本。因为 OpenLayers 5 之后的 API 有调整，postcompose 事件虽然还保留，但部分内部实现改了，这篇代码不能保证在 6.x、7.x 上原样跑通。如果你的地图对象是下面这种方式初始化的，就可以继续往下看：
var map = new ol.Map({ target: 'map', layers: [ new ol.layer.Tile({ source: new ol.source.OSM() }) ], view: new ol.View({ center: ol.proj.fromLonLat([121.4737, 31.2304]), zoom: 10 }) });如果你连这个初始化步骤都还没跑通，建议先回第一篇补个基础，或者直接用官方示例把地图显示出来。接下来所有代码都建立在 map 对象已经可以正常显示底图的基础上。
3.2 定义并注册遮罩渲染函数
OpenLayers 4 里实现 Canvas 叠加效果最标准的做法，是监听 map 的 postcompose 事件。这个事件会在每次地图帧渲染完成后触发，你可以在里面拿到 Canvas 渲染上下文，然后往上画任何东西。
先定义一个渲染遮罩的函数：
var highlightRegions = []; // 全局区域配置，动态更新 function renderMask(event) { if (!highlightRegions.length) { return; } var canvas = event.context; var ctx = canvas; var size = map.getSize(); // 保持画布状态，退出时恢复 ctx.save(); // 第一步：全图半透明遮罩 ctx.globalCompositeOperation = 'source-over'; ctx.fillStyle = 'rgba(0, 0, 0, 0.6)'; ctx.fillRect(0, 0, size[0], size[1]); // 第二步：合并所有区域路径 ctx.beginPath(); for (var i = 0; i < highlightRegions.length; i++) { var region = highlightRegions[i]; if (region.type === 'circle') { var centerPixel = map.getPixelFromCoordinate(ol.proj.fromLonLat(region.center)); var resolution = map.getView().getResolution(); var radiusPixel = region.radius / resolution; ctx.moveTo(centerPixel[0] + radiusPixel, centerPixel[1]); ctx.arc(centerPixel[0], centerPixel[1], radiusPixel, 0, Math.PI * 2); } else if (region.type === 'polygon') { var pixelCoords = region.coordinates.map(function(coord) { return map.getPixelFromCoordinate(ol.proj.fromLonLat(coord)); }); ctx.moveTo(pixelCoords[0][0], pixelCoords[0][1]); for (var j = 1; j < pixelCoords.length; j++) { ctx.lineTo(pixelCoords[j][0], pixelCoords[j][1]); } ctx.closePath(); } } // 第三步：挖洞 ctx.globalCompositeOperation = 'destination-out'; ctx.fillStyle = '#000'; ctx.fill(); ctx.restore(); } map.on('postcompose', renderMask);这段代码的关键点有两个。第一个是 circle 分支里的 moveTo 调用，很多人画完第一个圆后直接画第二个圆，结果两个圆之间会无端多出一条连接线。原因就是路径没有断开，Canvas 会把前一个图形的终点连到新图形起点。处理办法就是每个新图形开始前 moveTo 到当前图形边缘，这里我取的是圆心右侧半径处的一点，确保路径移动到圆上。
第二个关键点是 polygon 分支里的竖线问题。如果多边形没画完，直接进入下一个区域的 moveTo，OpenLayers 地图中间就会穿出一条对角线。所以每个多边形完成之后，必须 closePath()，让路径闭合。
3.3 动态更新：点击地图添加高亮区域
现在讲整个“（二）”里最有价值的动态更新环节。业务场景是这样的：用户点击地图上的某个位置，地图上就高亮显示以这个点为中心、半径 2000 米的圆形区域；再次点击别的位置，高亮区域就更新到新的位置；如果点击的是已经高亮的点，则取消它的高亮。
监听地图的单次点击事件：
map.on('singleclick', function(evt) { var lonLat = ol.proj.toLonLat(evt.coordinate); var existed = false; for (var i = 0; i < highlightRegions.length; i++) { var region = highlightRegions[i]; if (region.type === 'circle' && region.radius === 2000) { var dist = Math.sqrt( Math.pow(region.center[0] - lonLat[0], 2) + Math.pow(region.center[1] - lonLat[1], 2) ); if (dist < 0.01) { highlightRegions.splice(i, 1); existed = true; break; } } } if (!existed) { highlightRegions.push({ id: 'click_' + Date.now(), type: 'circle', center: [lonLat[0], lonLat[1]], radius: 2000, fillColor: 'rgba(0, 0, 0, 0.6)' }); } // 触发一次地图重绘 map.render(); });核心是最后一行的 map.render()。很多人改完 highlightRegions 数组后，发现地图不刷新，就是这个原因。OpenLayers 的 postcompose 事件是跟着渲染帧走的，单纯改数组不会主动触发渲染，你必须手动调用 map.render() 通知地图重新绘制一次。
我记得第一次做的时候漏掉了这个 render，调试了半小时才反应过来，还以为是自己数组操作写错了。现在养成了条件反射：任何 postcompose 里读取的数据，只要它变化了，就必须补一个 map.render()。
3.4 完整效果验证
跑起来以后，你应该看到的效果是：地图上所有未被高亮的区域都蒙上一层半透明黑色，点击的任意位置会露出一个半径 2000 米的圆形亮区，亮区内的地图清晰可见，亮区外的地图被黑色蒙层盖住。重复点击同一个点，亮区消失，蒙层恢复完整。这就是一个标准的多区域动态遮罩效果。
如果点完第一个点，再点第二个点，两个圆心之间如果有重叠地段，这个地段应该保持干净透明，不会出现重叠的半透明黑斑。这一点在早期版本里经常出问题，原因就是路径没合并，填了两次 destination-out 导致的，用上面合并路径的写法就能彻底避免。
4. 圆形高亮与事件联动：把遮罩从“画图”变成“交互层”
4.1 给遮罩区域绑定鼠标悬浮效果
遮罩本身不是目的，交互才是。一个很常见的需求是：鼠标悬浮在哪个高亮区域上，就给这个区域加一圈描边，同时在旁边弹一个小提示框，显示区域名称和覆盖范围。要实现这个效果，需要先解决一个问题：怎么判断鼠标当前在哪一个遮罩区域内部？
因为圆形区域最简单，这里只讲圆形的判断。监听地图的 pointermove 事件：
var hoveredRegionId = null; map.on('pointermove', function(evt) { if (evt.dragging) { return; } var coordinate = ol.proj.toLonLat(evt.coordinate); var foundRegionId = null; for (var i = 0; i < highlightRegions.length; i++) { var region = highlightRegions[i]; if (region.type !== 'circle') { continue; } var dx = coordinate[0] - region.center[0]; var dy = coordinate[1] - region.center[1]; var distanceInMeters = Math.sqrt(dx * dx + dy * dy) * 111320; // 粗略换算，1度纬度约111.32km if (distanceInMeters < region.radius) { foundRegionId = region.id; break; } } if (foundRegionId !== hoveredRegionId) { hoveredRegionId = foundRegionId; map.getTargetElement().style.cursor = hoveredRegionId ? 'pointer' : 'default'; map.render(); } });这里有一个粗略的经纬度换算：把经纬度差值乘 111320 得到一个近似米数。这个换算只在纬度不极端、且范围较小的情况下够用。如果你的区域跨度达到上百公里，或者在高纬度地区，建议用 ol.sphere.getDistance 做精确计算。这里的代码给的是一个简单直接可跑通的方案，你要用它做更严谨的业务，记得替换成精确算法。
4.2 在遮罩层上绘制描边与悬浮提示
上面判断出 hoveredRegionId 之后，还需要在渲染函数里对这个区域做差异化绘制。思路是在挖洞之前，先对 hovered 的区域单独画一个描边路径：
function renderMask(event) { // ... 前面的遮罩全图填充和路径收集保持不变 ... // 描边：只在 hoveredRegionId 有值时执行 if (hoveredRegionId) { ctx.globalCompositeOperation = 'source-over'; ctx.strokeStyle = '#ffd700'; ctx.lineWidth = 3; ctx.setLineDash([8, 4]); for (var i = 0; i < highlightRegions.length; i++) { var region = highlightRegions[i]; if (region.id !== hoveredRegionId) { continue; } if (region.type === 'circle') { var centerPixel = map.getPixelFromCoordinate(ol.proj.fromLonLat(region.center)); var resolution = map.getView().getResolution(); var radiusPixel = region.radius / resolution; ctx.beginPath(); ctx.arc(centerPixel[0], centerPixel[1], radiusPixel, 0, Math.PI * 2); ctx.stroke(); } break; } ctx.setLineDash([]); } }这里我用的 hovered 描边是在 postcompose 里同步绘制的，所以视觉上没有任何延迟，鼠标移过区域边缘的瞬间，虚线描边就会亮起来。
悬浮提示这块，建议不要用 Canvas 自己画气泡，维护成本太高。直接用 OpenLayers 的 Overlay 组件挂一个 HTML 元素上去，通过 pointermove 事件动态更新 Overlay 的位置和内容。代码如下：
var tooltip = new ol.Overlay({ element: document.getElementById('tooltip'), positioning: 'bottom-center', offset: [0, -10] }); map.addOverlay(tooltip); map.on('pointermove', function(evt) { var hoveredRegion = getHoveredRegion(evt.coordinate); if (hoveredRegion) { tooltip.setPosition(evt.coordinate); document.getElementById('tooltip').innerHTML = '<b>' + hoveredRegion.name + '</b><br/>覆盖半径：' + hoveredRegion.radius + '米'; tooltip.getElement().style.display = 'block'; } else { tooltip.getElement().style.display = 'none'; } });这个方案的优势是：提示框可以是任意 HTML 结构，可以带图片、可以加 CSS 动效、可以点击跳转，比 Canvas 画文字好用太多。
4.3 从高亮到业务动作：点击区域触发详情
既然鼠标悬浮都能判断了，点击触发业务逻辑就顺手了。监听 singleclick 事件，先判断点击位置是否落在任何高亮区域内。如果在，就调用业务回调，比如打开一个信息窗口；如果不在任何区域内，才执行“新增一个高亮区域”的逻辑。
判断代码可以复用 pointermove 里的 getHoveredRegion 逻辑。这样做的好处是交互逻辑非常统一：先判断点中谁，再决定干什么。我封装了一个函数：
function getHoveredRegion(coordinate) { for (var i = 0; i < highlightRegions.length; i++) { var region = highlightRegions[i]; if (region.type === 'circle') { var dx = coordinate[0] - region.center[0]; var dy = coordinate[1] - region.center[1]; var distanceInMeters = Math.sqrt(dx * dx + dy * dy) * 111320; if (distanceInMeters < region.radius) { return region; } } } return null; }这样 singleclick 事件和 pointermove 事件都复用同一个判断函数，不会出现“鼠标判断和点击判断对不上”的问题。
5. 性能优化与常见问题排查实录
5.1 拖动残影、闪烁、边界错位到底是怎么回事
这是所有遮罩方案里最容易被吐槽的问题。表现是：地图拖动过程中，遮罩层跟着地图一起移动，但遮罩里的“洞口”位置明显滞后，或者洞口边缘出现毛边、残影。很多人在这个问题上卡了好几天，最后实在受不了，用了一个笨办法：在 drag 开始时把遮罩隐藏，drag 结束后再画出来。这样做确实没有残影了，但体验非常差，遮罩会在拖动时一闪一闪地消失。
我先解释残影产生的根本原因。OpenLayers 4 的 postcompose 事件在每次渲染帧结束后触发。地图拖动时渲染帧是连续产生的，每一帧里地图底图已经移动到了新位置，但你基于上一帧的像素坐标画的遮罩洞口还没更新到最新位置，两者之间就会出现一个错位的帧。视觉上就是洞口拖了一个尾巴。
最有效的解决方案，不是避免在 postcompose 里绘制，而是使用离屏 Canvas 加缓存。思路是：只有当 highlightRegions 数组发生变化时，才重新绘制遮罩；地图平移、缩放过程中，不再实时计算每个区域的像素位置，而是直接把上一次绘制好的遮罩结果当图片贴上去。但这里有个细节：平移缩放会改变区域在图片里的位置，所以缓存画布必须和地图容器同尺寸，并且在地图移动时需要同步更新缓存的位置或重新计算偏移。
简单说，纯用 Canvas 缓存并不能完美解决拖动残影，只是把绘制频率降低了。真正让拖动时遮罩和地图“贴住”的，是要在地图的 moveend 事件里把缓存清掉，让下一次 postcompose 重绘一次。但这又会导致 moveend 之前的一两帧内遮罩是偏的。
后来我翻阅了 OpenLayers 社区的各种讨论，发现一个实用的折衷方案：把遮罩作为独立的 ImageLayer 或者使用自定义 Layer，而不是在 map 的 postcompose 里画。用独立图层，OpenLayers 的渲染引擎会帮你在移动时对图层做同步处理，不会再出现明显的错位。不过这个方案改造量有点大，不是每个项目都愿意。对于中小型项目，我推荐的做法是：保持 postcompose 绘制，但在地图的 movestart 事件里把遮罩区域的透明度降到 0.3 或更低，让它在拖动时视觉上不那么突兀；地图 moveend 之后再恢复原来的透明度并重绘。这样既不会闪，也看不出错位。
5.2 性能优化：离屏 Canvas 缓存提升重绘效率
如果高亮区域有几十个，每次 postcompose 都重新计算几十个区域的经纬度转像素，然后再画几十个路径，性能开销其实不小。更重要的是，很多区域在多次渲染之间根本没有变化，重复计算完全没必要。
优化方案是引入离屏 Canvas。第一次或者区域数据变化时，在离屏 Canvas 上绘制一次遮罩和挖洞结果，之后每次 postcompose 直接把离屏 Canvas 的绘制结果通过 drawImage 画到主画布上。
var maskCanvas = document.createElement('canvas'); var maskContext = maskCanvas.getContext('2d'); var needRedrawMask = true; function buildMaskCanvas() { var size = map.getSize(); maskCanvas.width = size[0]; maskCanvas.height = size[1]; // 清空 maskContext.clearRect(0, 0, size[0], size[1]); // 画遮罩 maskContext.globalCompositeOperation = 'source-over'; maskContext.fillStyle = 'rgba(0, 0, 0, 0.6)'; maskContext.fillRect(0, 0, size[0], size[1]); // 挖洞 maskContext.beginPath(); for (var i = 0; i < highlightRegions.length; i++) { // ... 与之前相同的路径收集逻辑 ... } maskContext.globalCompositeOperation = 'destination-out'; maskContext.fillStyle = '#000'; maskContext.fill(); needRedrawMask = false; } function renderMaskWithCache(event) { if (needRedrawMask) { buildMaskCanvas(); } event.context.drawImage(maskCanvas, 0, 0); }然后所有动态更新操作，比如 highlighRegions.push 或者 splice 之后，都要把 needRedrawMask 置为 true，让下一次渲染重新生成缓存。这个方案能把多区域场景下的渲染开销从 O(N) 降到 O(1)，N 再大都不怕。
5.3 常见问题速查表
这里整理我在实际集中开发碰到的几个高频问题，你照着排查可以省下大量时间。
场景一：遮罩画出来了，但洞没有透明，地图还是被盖住。原因通常是第二部没有设置 destination-out，或者 fillStyle 设置成了透明色。解决办法是确认 globalCompositeOperation 在调用 fill 之前已经切到 destination-out，并且 fillStyle 随便设一个不透明的颜色就行，因为它只负责擦除。
场景二：洞是透明的，但整张地图也跟着变透明了。这是因为在 fillRect 之前就开启了 destination-out，等于先把全图擦了一遍。确保第一步是 source-over，第二步才切换为 destination-out。
场景三：鼠标点击添加高亮区域后，地图没有任何反应。原因是忘了 map.render()。前面讲过，postcompose 是被动触发的，改数据不会自动引起重绘，必须手动调一下 map.render()。
场景四：地图初始化时遮罩没有显示，但点击一次后才出现。这通常是因为初始化时 highlightRegions 为空数组，postcompose 直接 return 了。后面填充数组后虽然调用了 map.render()，但如果目标区域用的是 ol.proj.fromLonLat，而地图投影不是默认的 EPSG:3857，坐标转换可能会出偏差。检查一下地图的 projection 配置，把所有经纬度统一用 ol.proj.fromLonLat 转，不要手动去改。
5.4 从遮罩效果到完整产品功能的思考
遮罩功能真正落到生产环境，还需要考虑一些细节。比如区域配置是从接口异步拉取的，拉回来之前地图上不能出现忽闪的遮罩；比如遮罩的透明度在不同显示屏上要有统一观感，不要在深色背景和浅色背景的屏幕上差异过大；再比如移动端触摸操作，singleclick 在触摸设备上是否会出现误触发，这都需要做额外处理。
这里我给一个建议：把遮罩配置和渲染逻辑彻底分离。配置管理单独抽一个模块，负责从接口拉数据、做增删改查、维护 highlightRegions 数组；渲染模块只负责读数组、判断 needRedrawMask、执行绘制。这样后面换地图库，比如从 OpenLayers 4 升级到 OpenLayers 7，或者换成 Leaflet，渲染模块重写就行，业务逻辑完全不用动。
还有个小技巧，如果你想给不同区域配不同的遮罩颜色，在 buildMaskCanvas 里的 fillRegionPath 函数中可以针对 region.fillColor 分别调用 fillRect 或者 fill，而不是统一在最后 fill。注意这样会从一次 fill 变成多次 fill，性能会略降，但视觉表现力会强很多。我之前做过一个案例：核心保护区用 0.7 透明度，缓冲协调区用 0.3 透明度，整个地图一眼就能看出等级的层次感，效果非常好。
6. 写在最后：一些个人体会
这套多区域遮罩方案，前后在不下五个项目里用过，从最开始简单的“全市核酸采样点分布高亮”，到后来“多个片区地块叠加分析”，核心逻辑都没怎么变过，都是数据驱动加离屏缓存这套组合拳。
我个人感受最深的一点是：遮罩效果看似很简单，但真正的复杂度从来不在“怎么画”上，而在“怎么画得稳、画得快、画得能和用户交互”。如果你只是写 demo，第一篇的代码完全够用；但如果你要做成一个长期维护的功能模块，从一开始就做好区域配置的数据结构、缓存重建的时机、事件判定的逻辑分离，后面会省非常多的事情。
另外，在我自己的电脑上实测，如果区域数量在 5 个以内，用不用缓存方案性能差异并不明显；但一旦超过 15 个，并且同时有鼠标悬浮动态判断，缓存方案带来的帧率提升立刻就能感知到。尤其是在低端笔记本上用 win10 跑 Chrome 测试时，差别特别明显。建议你写完基础版以后，直接把数据加到 50 个区域压测一下，再决定要不要上离屏缓存。
