用途：在 React + shadcn/ui 代码库中安装、集成、定制或排查 mapcn。适用于集成 mapcn、向 shadcn 项目添加 mapcn、使用 MapControls/Markers/Routes/Clusters、受控视口、useMap 钩子、MapLibre 组件等场景。前提是项目已使用 React，并已配置 Tailwind CSS 与 shadcn/ui。
主要能力：提供基于 MapLibre GL JS 的复制粘贴式地图组件。核心包括 Map 与受控视口（viewport + onViewportChange）、MapControls（showZoom、showCompass、showLocate、showFullscreen、position）、标记组件族（MapMarker、MarkerContent、MarkerPopup、MarkerTooltip、MarkerLabel）、独立弹窗 MapPopup、路径覆盖 MapRoute、以及用于密集点数据的 MapClusterLayer（GeoJSON 输入）。高级用法含 MapRef 执行 flyTo 等命令式操作、useMap 安全访问地图上下文并管理事件监听清理、styles 属性自定义 MapLibre 兼容样式。
使用方式：安装命令为 npx shadcn@latest add @mapcn/map，组件通常加入 components/ui，导入如 import { Map } from "@/components/ui/map"。地图容器必须显式设置高度，否则可能空白。简单场景用非受控模式，需要状态同步时改用受控视口。
适用场景与限制：适合中小规模标记（约数百点以内）；大数据集应改用 GeoJSON 图层与聚类渲染。需注意稳定 props 与处理函数以减少重渲染，并在高级事件中清理监听器。SSR 环境需确保客户端安全渲染，挂载前避免直接访问地图实例。排查空白地图时检查容器高度、样式 URL 有效性与瓦片请求是否被网络/CORS 拦截。不适用于非 React 框架，也不涉及超出默认无 key 基线的托管地图厂商账户设置。官方文档见 https://www.mapcn.dev/docs。