Vue高德地图遮罩实现：从官方Demo到项目实战-CSDN博客

1. 从官方Demo到项目实战：为什么你的遮罩不生效？

很多刚开始接触高德地图的Vue开发者，可能都经历过这样一个场景：你在高德地图的官方示例中心，找到了一个绘制区域遮罩的Demo，效果看起来非常酷。你兴冲冲地把那段示例代码复制下来，粘贴到自己的Vue项目里，满心期待地图上会出现一个完美的、半透明的遮罩层，只把你关心的区域高亮出来。

结果呢？浏览器控制台一片飘红，地图要么一片空白，要么遮罩的形状完全不对，甚至直接报错说“AMap is not defined”。这种感觉，就像照着菜谱做菜，每一步都“感觉”对了，但最后端出来的东西完全不能吃。我刚开始做地图相关项目时，也在这个坑里摔过好几次。

问题的根源在于，官方Demo通常是一个独立的、纯净的HTML/JavaScript环境。它直接通过<script>标签引入高德地图的JS API，所有的变量和对象都暴露在全局作用域下，代码可以很直接地调用AMap.Map、AMap.Polygon这些构造函数。但我们的Vue项目，是一个模块化的、经过构建工具（比如Webpack或Vite）打包的现代前端工程。这里涉及到几个关键差异：模块引入方式不同、生命周期管理不同、DOM渲染时机不同。官方Demo的代码是“一次性”的，页面加载完就执行；而Vue组件需要等待mounted生命周期，确保DOM容器已经真实挂载到页面上，才能进行地图初始化。如果你在created阶段就去初始化地图，很可能会因为找不到id="map"的DOM元素而失败。

所以，这篇文章的目的，就是帮你填平这个“Demo”与“项目”之间的鸿沟。我不会只给你一段看起来能跑的代码，而是会带你一步步拆解，告诉你每一步为什么要这么做，可能会遇到什么坑，以及如何根据你的实际项目需求进行调整。我们会从最基础的准备工作开始，到核心的遮罩绘制原理，再到性能优化和常见问题排查，最终让你能稳稳当当地在自己的Vue项目里实现任意复杂度的地图遮罩效果。

2. 实战前的核心准备：获取地图与区域数据

在动手写代码之前，有两样东西你必须准备好，这就像做饭前要备好菜和锅一样重要。

2.1 获取高德地图的“钥匙”：申请并引入JS API

首先，你需要去高德开放平台注册一个账号，并创建一个应用，以获取一个专属的Web端Key。这个Key是你的应用调用高德地图服务的凭证，没有它，地图根本加载不出来。这一步很多教程都提，但我发现新手最容易出错的地方在于引入方式。

在Vue项目中，我强烈推荐使用异步加载的方式引入高德地图JS API，而不是在index.html里写死一个<script>标签。为什么呢？因为异步加载不会阻塞页面其他资源的加载，对性能更友好，而且更符合Vue这类SPA应用的模块化思想。我通常会在项目的入口文件（比如main.js）或者一个单独的工具模块里，封装一个加载地图API的函数。

// utils/amap.js
export function loadAMapApi(key) {
  return new Promise((resolve, reject) => {
    if (window.AMap) {
      resolve(window.AMap);
      return;
    }
    // 创建script标签
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.src = `https://webapi.amap.com/maps?v=2.0&key=${key}&plugin=AMap.PolygonEditor`; // 这里可以按需添加插件
    script.onerror = reject;
    script.onload = () => {
      if (window.AMap) {
        resolve(window.AMap);
      } else {
        reject(new Error('高德地图API加载失败'));
      }
    };
    document.head.appendChild(script);
  });
}

这样，在你的Vue组件中，你就可以在mounted生命周期里，先确保API加载完成，再初始化地图。这个方法比在index.html里引入要灵活得多，特别是当你的应用有多个页面，但并非所有页面都需要地图时，可以做到按需加载。

2.2 找到区域的“轮廓”：下载正确的GeoJSON数据

遮罩，本质上就是在地图上画一个特殊的多边形：一个巨大的、覆盖整个地图视野的矩形作为“外框”，然后把你想要高亮的区域轮廓作为“内框”挖空。这个“内框”的形状数据，通常就是GeoJSON格式。

原始文章里提到的阿里云DataV地理小工具是一个非常好的资源站。你打开那个链接，就像进入了一个中国行政区划的“超市”，可以精确到区县一级下载对应的GeoJSON文件。这里我强调一个新手极易忽略的关键点：一定要选择“不含子区域”的版本。

这是什么意思呢？以“北京市”为例，“含子区域”的GeoJSON文件，它的geometry可能是一个MultiPolygon，里面包含了东城区、西城区、海淀区等所有区县的独立多边形。而“不含子区域”的版本，它会把这些区县的边界合并起来，形成一个完整的、代表整个北京市行政区域的、单一的多边形。对于遮罩效果来说，我们需要的是后者——一个完整的、封闭的轮廓。如果你用了“含子区域”的版本，画出来的遮罩可能会是一堆散乱的小块，中间会有缝隙，效果就完全不对了。

下载下来的GeoJSON文件，你可以放在项目的public目录下（这样可以通过相对路径直接访问），或者上传到你的静态资源服务器。我更倾向于后者，因为GeoJSON文件可能不小，放在项目里会增大打包体积。在代码中，我们通过axios或fe