shallowRef 用于安全持有地图原生实例（如 AMap.Map），避免 Proxy 劫持导致方法失效、聚合异常和内存泄漏；标记点数组用 ref 管理，但删除必须调用 SDK 原生 API，不可仅清空数组。
在 Vue 3 地图组件中管理海量标记点时，shallowRef 的核心作用不是存标记点数据本身，而是安全持有地图原生实例（如 AMap.Map、T.Map 或 L.Map），避免响应式系统污染其内部方法和生命周期。标记点数组本身应使用 ref 管理，但需配合地图 API 的原生删除逻辑，不能仅靠响应式更新。
为什么必须用 shallowRef 存地图实例
地图 SDK 实例（比如高德的 AMap.Map、天地图的 T.Map）是重型原生对象，内部含大量函数、事件监听器和 DOM 引用。若用 ref 包裹，Vue 的 Proxy 会尝试劫持其所有属性，导致：
- 方法被转为不可调用的 getter/setter，调用
map.removeLayer()报错或静默失败 - 聚合插件（如
AMap.MarkerClusterer）内部校验失效，出现vg、ud等异常码 - 内存泄漏：Proxy 代理无法被 GC 正常回收
而 shallowRef 只追踪 .value 的替换（例如从 null → 实例），不深入拦截内部属性，完美适配这类“只读容器型”对象。
标记点数组用 ref，但删除要走原生 API
海量标记点（如成百上千个 AMap.Marker 或 T.Marker）应存在普通数组中，并用 ref 包裹以便 Vue 响应式更新 UI 状态（如选中高亮）。但真正从地图上移除，必须调用地图 SDK 提供的方法，而非清空 ref 数组：
审查 Vue 管理后台的变更请求（Vue 2 + Element UI，Vue 3 + Element Plus）。重点关注最小化变更实现、上线风险检查以及回归检查清单生成。
- 高德地图：
marker.setMap(null)或map.remove(marker)，再手动从markers.value中splice或filter - 天地图：
map.removeOverlay(marker)，且需确保marker是通过map.addOverlay()添加的原始实例 - Leaflet：
markersLayer.clearLayers()或marker.remove()，再同步清理markers.value
常见错误：只执行 markers.value = [] —— 标记点仍在地图上，只是响应式数组空了，造成内存和视觉双重残留。
聚合场景下的关键配合
启用聚合（如高德 MarkerClusterer、Leaflet markerClusterGroup）时，更需注意：
- 聚合管理器（如
cluster实例）也必须用shallowRef存储，不能用ref - 添加标记点时，是往聚合器里加（
cluster.addMarkers(markers)），不是直接加到地图 - 清空时，先调用
cluster.clearLayers()，再重置markers.value；不能只清数组 - 动态更新时，避免反复新建聚合器，应复用实例并调用
refreshClusters()类方法
实际声明与清理示例（高德地图）
以下写法兼顾安全性与可维护性：
const map = shallowRef(null)
const cluster = shallowRef(null)
const markers = ref([]) // 存 Marker 实例数组
// 初始化后
map.value = new AMap.Map('map', { ... })
cluster.value = new AMap.MarkerClusterer(map.value, [])
// 添加一批点
const newMarkers = source.map(item => new AMap.Marker({ position: item.lnglat }))
markers.value.push(...newMarkers)
cluster.value.addMarkers(newMarkers)
// 安全清空
if (cluster.value) cluster.value.clearMarkers()
markers.value = []
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
