WordPress自定义Google Map MarkerClusterer标记不聚类问题求助

按优先级排查核心问题 #

1. 聚类库是否正确加载 #

这是90%聚类失效的根源：必须在Google Maps API的加载URL中添加&libraries=markerclusterer参数，示例：

<script src="https://maps.googleapis.com/maps/api/js?key=你的API密钥&libraries=markerclusterer"></script>

如果用WordPress的wp_enqueue_script加载自定义JS，一定要把Google Maps API设为依赖项，确保聚类库先于你的代码加载完成。

2. Markers数组是否真的被填充 #

• 确认标记数量≥2（少于2个不会触发聚类），可以在push标记后加console.log(markers.length)验证数组长度。
• 若通过异步请求（比如WP REST API）获取位置数据，绝对不能在异步回调外初始化聚类——此时数组仍为空，示例：

// 错误写法：聚类初始化在异步回调外
let markers = [];
fetch('/wp-json/locations/v1/all')
  .then(res => res.json())
  .then(data => {
    data.forEach(loc => markers.push(new google.maps.Marker({position: loc.coords, map: map})));
  });
new MarkerClusterer({map: map, markers: markers}); // 此处markers为空

// 正确写法：聚类初始化放在异步回调内
fetch('/wp-json/locations/v1/all')
  .then(res => res.json())
  .then(data => {
    const markers = data.map(loc => new google.maps.Marker({position: loc.coords, map: map}));
    new MarkerClusterer({map: map, markers: markers});
  });

3. 聚类初始化语法是否合规 #

Google已废弃旧版MarkerClusterer构造函数，需使用新版语法：

// CDN加载时的全局对象写法
const clusterer = new google.maps.markerClusterer.MarkerClusterer({
  map: 你的地图实例,
  markers: 标记数组,
  // 可选：添加自定义样式，确保聚类效果可见
  renderer: {
    render: ({ count, position }) => {
      return new google.maps.Marker({
        label: { text: String(count), color: '#fff', fontSize: '12px' },
        position: position,
        icon: { url: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m', scaledSize: new google.maps.Size(40, 40) }
      });
    }
  }
});

4. 脚本加载顺序是否冲突 #

• 自定义JS必须在Google Maps API完全加载后执行，建议用google.maps.event.addDomListener(window, 'load', 你的初始化函数)包裹逻辑。
• WordPress中使用wp_enqueue_script时，设置in_footer: true，避免DOM未加载就执行代码。

5. 标记是否正确添加到地图 #

检查每个标记的map属性是否指向你的地图实例，若标记未显示在地图上，聚类自然无法生效。

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