高德地图离线部署方案：获取瓦片数据与私有化调用

一、概述

在开发内网应用或需要高安全性的系统时，第三方在线地图服务（如高德、百度、腾讯等）因依赖互联网连接而无法直接使用。为了解决这一问题，本文介绍如何通过本地部署高德地图瓦片数据和 JS API，将网络请求全部转换为本地请求，从而实现地图服务的私有化部署。

二、环境准备

操作系统：Windows 或 Linux 均可。
开发工具：推荐使用 VS Code 或 WebStorm。
运行环境：Node.js (建议 v14+), Vue CLI。
静态资源服务器：由于涉及本地文件读取，建议使用 Nginx 或 Webpack Dev Server 提供静态服务，避免直接打开 HTML 文件导致的跨域问题。

三、爬取瓦片数据

1. 获取地图下载器

使用开源的地图瓦片图下载工具，支持 OpenStreetMap、天地图、谷歌地图、高德地图、腾讯地图、必应地图的 XYZ 瓦片图下载与合并。此类工具通常基于 Java 开发，需确保运行环境配置正确。

注意：程序运行路径必须为全英文路径，避免中文路径导致解压或运行错误。

2. 下载地图瓦片数据

下载并解压工具包，运行 run.bat 启动程序。
选择地图资源类型，根据需求选择省份或城市范围。
设置层级：层级越高瓦片数量越多，加载速度越慢。一般业务场景下，12 层至 18 层即可满足大部分展示需求。
命名风格选择 {z}/{x}/{y}.png，指定下载位置。
点击下载开始任务，等待完成。

四、获取高德离线开发包

高德官方提供了离线开发包，包含必要的 JS 文件和样式资源。开发者需从官方渠道或可信仓库获取，确保版本兼容性。

提示：请务必参考高德地图开放平台最新文档，确认 API Key 的申请方式及限制条件。部分功能可能需要申请特定的 Key 才能生效。

五、项目集成步骤

以 Vue 项目为例，演示如何将离线包和瓦片数据集成到前端应用中。

1. 资源目录结构

将下载的瓦片数据和离线包放入项目的 public 目录下，保持原有文件夹结构不变。

public/
├── amap/          # 高德离线 JS 包
│   ├── AMap3.js
│   └── ...
└── MAP_zxy/       # 地图瓦片数据
    ├── 0/
    │   └── ...
    └── 12/
        └── ...

2. 引入离线脚本

在组件中直接加载 amap 文件夹下的 AMap3.js。其余文件不可删除，否则可能导致功能缺失。

import "../../public/amap/AMap3.js"

3. 定义地图容器

在模板中定义用于显示地图的 DOM 元素。

<div id='map-container' style="width: 100%; height: 600px;"></div>

4. 初始化地图实例

在代码中直接 new AMap.Map。Vue 项目中无需额外导入 map 插件配置，但需自定义图层以指向本地瓦片。

完整代码示例

以下是一个完整的 MapView.vue 组件示例，展示了地图初始化、标记点、折线及文本标注的实现。

<template>
  <div class="map-wrapper">
    <div id='map-container' style="width: 100%; height: 600px;"></div>
    <div class="controls">
      <button @click="handleMarker">添加标记</button>
      <button @click="handlePolyline">绘制折线</button>
      <button @click="handleTextmark">添加文本</button>
    </div>
  </div>
</template>

<script>
// 引入高德离线 JS 库
import "../../public/amap/AMap3.js"

export default {
  data() {
    return {
      mapObj: null,
      base_url: "/",
    }
  },

  methods: {
    initMap() {
      // 自定义地图层，指向本地瓦片
      const layers = [new AMap.TileLayer({
          getTileUrl: function (x, y, z) {
              return `${this.base_url}MAP_zxy/${z}/${x}/${y}.png`;
          },
          opacity: 1,
          zIndex: 99,
      })]

      this.mapObj = new AMap.Map('map-container', {
          resizeEnable: true,
          zoom: 15,
          rotateEnable: true,
          pitchEnable: true,
          center: [113.098980, 23.361340],
          defaultCursor: 'pointer',
          showLabel: true,
          layers: layers,
      })
    },
    
    handleMarker() {
      const marker = new AMap.Marker({
        position: [113.098980, 23.361340],
      });
      this.mapObj.add(marker);
    },

    handlePolyline() {
      const lineArr = [
        [113.098980, 23.361340],
        [113.092980, 23.361340],
        [113.092980, 23.366340]
      ];
      const polyline = new AMap.Polyline({
        path: lineArr,
        strokeColor: "red",
        strokeWeight: 5,
        strokeStyle: "solid",
      });
      this.mapObj.add(polyline);
    },

    handleTextmark() {
      let text = new AMap.Text({
          text: '粤电花都燃气电厂',
          anchor: 'center',
          draggable: true,
          cursor: 'pointer',
          angle: 10,
          style: {
              'padding': '.75rem 1.25rem',
              'margin-bottom': '1rem',
              'border-radius': '.25rem',
              'background-color': 'white',
              'width': '10rem',
              'border-width': 0,
              'box-shadow': '0 2px 6px 0 rgba(114, 124, 245, .5)',
              'text-align': 'center',
              'font-size': '20px',
              'color': 'blue'
          },
          position: [113.098980, 23.362240]
      });
      text.setMap(this.mapObj);

      let text1 = new AMap.Text({
          text: '双一橡胶',
          anchor: 'center',
          draggable: true,
          cursor: 'pointer',
          angle: 10,
          style: {
              'padding': '.75rem 1.25rem',
              'margin-bottom': '1rem',
              'border-radius': '.25rem',
              'background-color': 'white',
              'width': '10rem',
              'border-width': 0,
              'box-shadow': '0 2px 6px 0 rgba(114, 124, 245, .5)',
              'text-align': 'center',
              'font-size': '20px',
              'color': 'blue'
          },
          position: [113.092980, 23.366340]
      });
      text1.setMap(this.mapObj);
    },
  },

  mounted() {
    this.initMap()
  }
}
</script>

<style scoped>
.map-wrapper {
  position: relative;
}
.controls {
  margin-top: 10px;
}
.controls button {
  margin-right: 10px;
  padding: 5px 10px;
}
</style>

六、常见问题排查

1. 跨域问题 (CORS)

如果地图瓦片无法加载，通常是浏览器安全策略限制了本地文件访问。解决方案包括：

使用 Nginx 或 Apache 搭建本地静态服务器，通过 HTTP 协议访问瓦片。
修改浏览器启动参数禁用安全检查（仅限开发环境）。
确保服务器响应头允许跨域访问。

2. 路径配置错误

getTileUrl 中的 base_url 必须与实际部署路径一致。如果使用相对路径，请确保当前页面 URL 能正确解析到瓦片目录。

3. 内存占用过高

瓦片数据量较大时，浏览器缓存可能不足。建议仅下载业务所需区域的瓦片，并合理控制最大层级（如 12-15 层）。

七、总结

通过上述步骤，开发者可以在无互联网环境下实现高德地图的完整功能。关键在于正确配置瓦片路径和 JS 库引用。此方案适用于内网监控、工业大屏、涉密系统等对数据安全有严格要求的场景。

高德地图离线部署方案：获取瓦片数据与私有化调用