Leaflet 开发常见雷区与避坑要点
Leaflet 开发常见雷区主要集中在五类:地图容器未设明确高度或未引入 CSS 导致灰屏/空白、动态尺寸变化后未调用 invalidateSize()、1.x 下 bundler 改写默认 Marker 图标路径致 404、坐标写成 [lng, lat] 颠倒,以及从 1.x 迁到 2.0 时忽略 ES modules、类写法与浏览器基线变更。把这几处一次处理好,地图就能稳定渲染、少踩坑。截至 2026 年 11 月,npm 默认仍安装稳定版 1.9.4,2.0.0-beta.2 已于 11 月 6 日发布,接近最终版。

地图显示灰屏或空白时先查这三项
灰屏、空白或瓦片堆叠是最常见的“看起来坏了”的情况,通常不是 Leaflet 本身崩了,而是初始化条件没满足。地图瓦片与 pane 采用绝对定位,不会把容器撑开;CSS 没加载时图标与控件样式全部失效。
- 容器必须有明确高度(如 400px、100vh,或百分比且父级有高度),否则渲染区域高度为 0。
- 必须引入 leaflet.css(或 2.0 的 styles.css),否则会出现灰盒、瓦片错位、控件乱飞。
- 必须添加至少一个 TileLayer(如 OSM),并确认 network 里瓦片请求成功返回。
可按下面顺序快速验收:
- 给地图 div 写死高度并确认父级也有高度。
- 确认 CSS 已正确引入且无 404。
- 添加 TileLayer 后刷新,看瓦片是否逐块出现。
- 打开开发者工具 Network,过滤瓦片域名,确认状态码 200。
若仍灰,检查是否在 display:none 的隐藏容器里初始化(此时尺寸为 0),或是否被框架(React/Vue 弹层、Tab)延迟显示。
容器尺寸变化后地图不刷新怎么办
Leaflet 在初始化时缓存容器尺寸,不会自动感知后续 resize、侧边栏折叠、弹窗打开、CSS transition 结束等情况。结果是瓦片缺块、中心偏移或控件错位。2.0 在部分场景有改进,但仍建议手动处理。
标准做法是在尺寸稳定后调用 map.invalidateSize()。常见触发时机:
- 窗口 resize 事件(可加防抖)。
- Tab/Modal/侧边栏动画结束后(常用 setTimeout 等过渡完成)。
- 用 ResizeObserver 监听容器本身。
验收标准:改变容器宽高后,瓦片完整铺满、中心点不跳、缩放控件位置正确。若在隐藏状态初始化,先显示再 invalidateSize,否则无效。

默认 Marker 图标丢失与 1.x / 2.0 差异
1.x 默认图标依赖 CSS 相对路径的 PNG。Webpack、Vite 等 bundler 会改写路径,导致 _getIconUrl 检测失败并 404,地图上出现破碎图标。这是 1.x 在工程化项目里的高频雷区。
1.x 临时方案通常是手动 mergeOptions 指定 iconUrl / iconRetinaUrl / shadowUrl,或使用兼容插件,或设置 imagePath。这些 workaround 在 2.0 会破坏,不要照搬。
2.0 已改为默认 inline SVG Marker,bundler 与 CDN 开箱即用,还可直接着色与旋转,彻底消除图标路径问题。当前最新预发布为 2.0.0-beta.2(2026 年 11 月 6 日),可在官方发布页核对。
| 项目 | 1.9.4(稳定) | 2.0 beta |
|---|---|---|
| 默认 Marker | PNG + 相对路径,bundler 易 404 | inline SVG,开箱即用可着色 |
| 模块与类型 | 传统全局 L / UMD | 纯 ES modules + 内置 TypeScript |
| 体积(gzipped 参考) | 约 38–40 KB | 带 TileLayer 约 25.6 KB,可 tree-shake |
| 浏览器基线 | 含 IE9–11 等较旧环境 | Baseline 2022(无 IE,无 polyfill) |
| npm 安装 | npm install leaflet | npm install leaflet@beta |
选型建议:生产环境优先 1.9.4 直至 2.0 正式发布;新项目或可接受 Baseline 2022 的可提前用 beta 验证插件兼容性。迁移细节见官方 1.x 到 2.0 迁移指南。
坐标顺序、瓦片源与 attribution 必须守的规矩
Leaflet 坐标一律是 [latitude, longitude],与部分库(如某些 Google 接口习惯)相反。写反后点会飞到海里或完全偏移,排查时先打印经纬度对。CRS 默认是 EPSG:3857(Web Mercator),自定义投影或本地坐标系时需明确设置,否则叠加错位。
瓦片提供商无关(OSM、Mapbox、MapTiler、Esri 等均可),但必须遵守各自服务条款并正确显示 attribution。缺少 attribution 既违反条款,也可能在部分环境下被拒载。Google 瓦片需走官方 Map Tiles API 或经许可的插件,随意抓取不可取。
- 创建 Marker / setView / fitBounds 时始终检查 lat 在前。
- TileLayer 的 attribution 选项写清楚来源。
- 商业项目先读瓦片商条款,必要时换成付费或自建服务。
- 更多许可与数据源说明可参考官方 Leaflet FAQ。
图层过多或频繁增删时,注意清理事件监听与移除图层,避免内存与重绘压力;移动端注意 touch 与 pointer 事件差异(2.0 已统一到 Pointer Events)。
常见问题
为什么我加了瓦片还是一片灰?
优先检查容器高度是否为 0、CSS 是否引入成功、是否在隐藏容器里初始化。三者任一不满足都会灰屏,与瓦片 URL 无关。
弹窗或侧边栏打开后地图缺一块怎么办?
在动画或布局结束后调用 map.invalidateSize()。用 setTimeout 或 ResizeObserver 均可,务必等尺寸真正变化完成再调。
1.x 项目里默认图标老是 404,升级 2.0 能直接解决吗?
能。2.0 改用 inline SVG,不再依赖图片路径。但需同步改成 named import 与新类写法,并去掉旧的 mergeOptions 补丁,否则反而出错。
现在该用 1.9.4 还是 2.0 beta?
正式生产继续用 1.9.4(npm 默认);需要 tree-shaking、内置类型、更好无障碍与更小体积时可试用 2.0.0-beta.2,并同步测试所用插件。以官方发布页为准。
总结:先保证容器高度 + CSS + TileLayer,再处理 resize 与 invalidateSize,坐标永远 lat 在前,1.x 图标问题用正确路径或直接迁 2.0。建议新项目按 Baseline 2022 评估是否提前用 2.0 beta;存量项目保持 1.9.4 并写好尺寸与 attribution 检查清单,上线前用真实容器尺寸与网络环境验收一遍即可大幅降低雷区。