如何在Nuxt 3项目中正确使用leaflet.markercluster？

问题背景 #

生产环境使用Nuxt3、TypeScript、组合式API结合Leaflet开发地图应用，随着标记数量增加，尝试引入leaflet.markercluster实现标记分组，但因SSR环境下执行客户端方法导致500错误，无法正常工作。

解决方案 #

1. 确认依赖安装 #

确保package.json中已正确包含相关依赖（你的配置已满足，若未安装则执行以下命令）：

npm install leaflet.markercluster @types/leaflet.markercluster

2. 调整Nuxt客户端插件配置 #

修改leaflet.client.ts，确保leaflet.markercluster仅在客户端加载并扩展Leaflet：

import {
  LIcon,
  LMap,
  LMarker,
  LPopup,
  LTileLayer,
} from "@vue-leaflet/vue-leaflet";
import L from "leaflet";
// 导入markercluster及样式
import "leaflet.markercluster";
import "leaflet.markercluster/dist/MarkerCluster.css";
import "leaflet.markercluster/dist/MarkerCluster.Default.css";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component("LMap", LMap);
  nuxtApp.vueApp.component("LTileLayer", LTileLayer);
  nuxtApp.vueApp.component("LMarker", LMarker);
  nuxtApp.vueApp.component("LIcon", LIcon);
  nuxtApp.vueApp.component("LPopup", LPopup);

  return {
    provide: {
      L,
    },
  };
});

3. 在Map组件中安全创建MarkerClusterGroup #

由于SSR环境无法执行Leaflet客户端方法，需将Cluster的创建逻辑放在客户端生命周期钩子或地图ready事件中：

修改Map.vue的脚本部分：

<script setup lang="ts">
import {LIcon, LMap, LMarker, LPopup, LTileLayer} from "@vue-leaflet/vue-leaflet";
import "leaflet/dist/leaflet.css";
import { useNuxtApp } from '#app';

const nuxtApp = useNuxtApp();
const L = nuxtApp.$L; // 获取插件提供的Leaflet实例

const leafletOptions = ref({
  url: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
  minZoom: 5,
  maxZoom: 13,
  zoom: 5.5,
  map: null,
  center: [47.040182, 2.536054],
  bounds: null,
  overlayLocation: false,
  colors: ["#ED722E", "#F6BE00", "#979B0B", "#DA2C81"],
});

const locations = ref([]); // 假设已通过API获取到位置数据
const markerCluster = ref(null);

// 地图就绪时创建Cluster并添加标记
const onLeafletReady = (mapInstance) => {
  // 创建MarkerClusterGroup
  markerCluster.value = L.markerClusterGroup();
  
  // 遍历位置，创建标记并添加到Cluster
  locations.value.forEach(location => {
    if (location.attributes.active && location.attributes.lat && location.attributes.long) {
      const marker = L.marker([location.attributes.lat, location.attributes.long]);
      // 绑定弹窗（如果需要）
      const popup = L.popup({ className: "text-center flex flex-col gap-y-4" })
        .setContent(`<!-- 替换为你的弹窗内容 -->`);
      marker.bindPopup(popup);
      // 添加自定义图标（如果需要）
      const icon = L.icon({
        // 替换为你的图标配置，比如iconUrl、iconSize等
      });
      marker.setIcon(icon);
      
      markerCluster.value.addLayer(marker);
    }
  });
  
  // 将Cluster添加到地图
  mapInstance.addLayer(markerCluster.value);
};
</script>

4. 简化模板结构 #

移除模板中直接循环渲染l-marker的代码，仅保留地图和瓦片层：

<client-only>
  <l-map 
      ref="locationsMap"
      :min-zoom="leafletOptions.minZoom"
      :max-zoom="leafletOptions.maxZoom"
      :zoom-animation="true"
      :zoom="leafletOptions.zoom"
      :center="leafletOptions.center"
      :useGlobalLeaflet="false"
      :options="{ tap: false }"
      @ready="onLeafletReady">
        <l-tile-layer :url="leafletOptions.url"/>
  </l-map>
</client-only>

关键说明 #

• 所有涉及Leaflet客户端API的操作（如创建markerClusterGroup、标记、弹窗等）必须放在客户端环境中执行，避免SSR阶段触发错误。
• 通过Nuxt插件提供的$L实例确保Leaflet及markercluster的扩展全局可用，且仅在客户端加载。
• 若需保留Vue-Leaflet组件式开发，可将l-marker的渲染逻辑封装到client-only包裹的独立子组件中，但脚本方式创建标记并添加到Cluster的可靠性更高。

内容的提问来源于stack exchange，提问作者antoinelzch