保姆级教程：在Vue项目里用MapLibre GL JS加载天地图WMTS服务（附完整代码）

最新推荐文章于 2026-06-18 20:53:02 发布

原创最新推荐文章于 2026-06-18 20:53:02 发布 · 397 阅读

8 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Vue #MapLibre GL JS #天地图 #前端开发 #ViewUI

Vue项目集成MapLibre GL JS与天地图WMTS服务实战指南

最近在开发一个需要展示地理信息的Vue项目时，我遇到了一个常见需求：如何在现代前端框架中高效加载并展示地图数据。经过多次尝试和优化，最终选择了MapLibre GL JS作为地图渲染引擎，配合天地图的WMTS服务，实现了高性能的地图展示功能。本文将分享这一过程中的关键步骤和实战经验。

1. 环境准备与基础配置

在开始编码之前，我们需要确保开发环境准备就绪。首先创建一个新的Vue项目（如果你还没有），这里推荐使用Vue 3的组合式API，它能更好地管理地图实例的状态。

安装必要的依赖：

npm install maplibre-gl vue-maplibre

天地图服务需要先申请开发者密钥，访问天地图官网注册账号并创建应用即可获取。这个key将用于后续所有的瓦片请求认证。

在项目根目录下创建 .env 文件存储环境变量：

VUE_APP_TIANDITU_KEY=你的天地图密钥

2. 构建地图服务配置模块

为了保持代码的整洁和可维护性，我建议将地图相关的配置单独放在一个模块中。创建 src/utils/mapConfig.js 文件：

export const tdtSources = {
  vec_w: {
    type: 'raster',
    tiles: [
      `https://t0.tianditu.gov.cn/vec_w/wmts?tk=${process.env.VUE_APP_TIANDITU_KEY}&SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles`
    ],
    tileSize: 256
  },
  cva_w: {
    type: 'raster',
    tiles: [
      `https://t0.tianditu.gov.cn/cva_w/wmts?tk=${process.env.VUE_APP_TIANDITU_KEY}&SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles`
    ],
    tileSize: 256
  }
};

export const baseMapStyle = {
  version: 8,
  sources: {
    'tdt-vec': tdtSources.vec_w,
    'tdt-cva': tdtSources.cva_w
  },
  layers: [
    {
      id: 'tdt-vec-layer',
      type: 'raster',
      source: 'tdt-vec',
      minzoom: 0,
      maxzoom: 18
    },
    {
      id: 'tdt-cva-layer',
      type: 'raster',
      source: 'tdt-cva',
      minzoom: 0,
      maxzoom: 18
    }
  ]
};

3. Vue组件实现与地图生命周期管理

在Vue单文件组件中集成MapLibre需要特别注意实例的生命周期管理。下面是一个完整的组件实现示例：

<template>
  <div class="map-container" ref="mapContainer"></div>
</template>

<script>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import maplibregl from 'maplibre-gl';
import { baseMapStyle } from '@/utils/mapConfig';

export default {
  name: 'TianDiMap',
  setup() {
    const mapContainer = ref(null);
    const mapInstance = ref(null);
    const initialCenter = [116.404, 39.915]; // 北京天安门坐标
    const initialZoom = 10;

    const initMap = () => {
      if (!mapContainer.value) return;

      mapInstance.value = new maplibregl.Map({
        container: mapContainer.value,
        style: baseMapStyle,
        center: initialCenter,
        zoom: initialZoom,
        attributionControl: false
      });

      // 添加地图控件
      mapInstance.value.addControl(new maplibregl.NavigationControl());
      mapInstance.value.addControl(new maplibregl.ScaleControl());

      // 解决常见的水印偏移问题
      mapInstance.value.on('load', () => {
        const watermark = document.querySelector('.maplibregl-ctrl-bottom-right');
        if (watermark) {
          watermark.style.right = '10px';
          watermark.style.bottom = '30px';
        }
      });
    };

    onMounted(() => {
      initMap();
    });

    onBeforeUnmount(() => {
      if (mapInstance.value) {
        mapInstance.value.remove();
        mapInstance.value = null;
      }
    });

    return {
      mapContainer
    };
  }
};
</script>

<style scoped>
.map-container {
  width: 100%;
  height: 100%;
  position: absolute;
  top: 0;
  left: 0;
}
</style>

4. 性能优化与常见问题解决

在实际项目中，地图性能优化至关重要。以下是我总结的几个关键优化点：

按需加载地图资源 ：
- 只在需要时初始化地图
- 使用动态导入减少初始包大小

内存管理 ：

// 在组件销毁时清理地图资源
onBeforeUnmount(() => {
  if (mapInstance.value) {
    mapInstance.value.remove();
    mapInstance.value = null;
  }
});

跨域问题解决方案 ：

配置代理服务器绕过浏览器限制

在vue.config.js中添加代理配置：

module.exports = {
  devServer: {
    proxy: {
      '/tianditu': {
        target: 'https://t0.tianditu.gov.cn',
        changeOrigin: true,
        pathRewrite: {
          '^/tianditu': ''
        }
      }
    }
  }
}

移动端适配技巧 ：

// 在初始化地图时添加移动端优化配置
const mapOptions = {
  container: mapContainer.value,
  style: baseMapStyle,
  center: initialCenter,
  zoom: initialZoom,
  interactive: true,
  trackResize: true,
  renderWorldCopies: false, // 提升移动端性能
  pitchWithRotate: false // 禁用不必要的3D效果
};

5. 高级功能扩展

基础地图加载完成后，我们可以进一步扩展功能：

添加自定义图层 ：

mapInstance.value.on('load', () => {
  mapInstance.value.addSource('custom-points', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: [
        // 你的地理要素数据
      ]
    }
  });
  
  mapInstance.value.addLayer({
    id: 'points-layer',
    type: 'circle',
    source: 'custom-points',
    paint: {
      'circle-radius': 8,
      'circle-color': '#FF0000'
    }
  });
});

实现地图交互 ：

const setupMapInteractions = () => {
  // 点击事件
  mapInstance.value.on('click', (e) => {
    const features = mapInstance.value.queryRenderedFeatures(e.point);
    console.log('Clicked features:', features);
  });
  
  // 鼠标移动事件
  mapInstance.value.on('mousemove', (e) => {
    const features = mapInstance.value.queryRenderedFeatures(e.point);
    // 更新UI或显示工具提示
  });
};

响应式地图控制 ：

// 使用Vue的响应式系统控制地图状态
const currentZoom = ref(initialZoom);

watch(currentZoom, (newVal) => {
  if (mapInstance.value) {
    mapInstance.value.zoomTo(newVal);
  }
});

6. 样式定制与主题切换

MapLibre GL JS支持灵活的地图样式定制。我们可以创建多个主题并实现动态切换：

定义不同主题 ：

export const darkMapStyle = {
  version: 8,
  sources: {
    'tdt-vec': tdtSources.vec_w,
    'tdt-cva': tdtSources.cva_w
  },
  layers: [
    {
      id: 'tdt-vec-layer',
      type: 'raster',
      source: 'tdt-vec',
      minzoom: 0,
      maxzoom: 18,
      paint: {
        'raster-opacity': 0.7,
        'raster-contrast': 0.5,
        'raster-brightness-min': 0.2
      }
    },
    // 其他图层配置
  ]
};

实现主题切换功能 ：

const currentTheme = ref('light');

const switchTheme = () => {
  if (!mapInstance.value) return;
  
  currentTheme.value = currentTheme.value === 'light' ? 'dark' : 'light';
  const newStyle = currentTheme.value === 'light' ? baseMapStyle : darkMapStyle;
  
  mapInstance.value.setStyle(newStyle);
};

自定义控件UI ：

const addCustomControls = () => {
  // 创建自定义控件容器
  const customControl = document.createElement('div');
  customControl.className = 'maplibregl-ctrl custom-control';
  
  // 添加控件内容
  const themeButton = document.createElement('button');
  themeButton.textContent = '切换主题';
  themeButton.addEventListener('click', switchTheme);
  customControl.appendChild(themeButton);
  
  // 添加到地图
  mapInstance.value.addControl({
    onAdd: () => customControl,
    onRemove: () => {}
  }, 'top-right');
};