Leaflet 地图初始化与视图设置
Leaflet 地图初始化的核心是准备一个有明确高度的容器，再用构造函数创建地图实例并设定初始中心与缩放。截至 2026 年 11 月，稳定版仍是 1.9.4（用 L.map），最新预发布版是 2.0.0-beta.2（用 new LeafletMap，纯 ES 模块）。两者都支持通过 options 传入 center/zoom，或链式调用 setView；之后可用 setZoom、fitBounds、flyTo、setMaxBounds 等方法精确控制视图。容器高度为 0、未引入 CSS 或重复初始化是最常见的失败原因。
如何正确初始化一张 Leaflet 地图
先解决“地图出不来”的问题，再谈视图。地图容器必须在调用构造函数前已存在于 DOM，并且 CSS 给了明确高度（常见写法是 400px 或 100vh）。2.0 默认启用鼠标/触摸交互、缩放控件和 attribution，多数方法返回 this，方便链式调用。
- 在 HTML 里放一个容器：<div id=”map”></div>，并在样式里写 #map { height: 400px; width: 100%; }。
- 引入 Leaflet CSS（2.0 为 styles.css，1.x 为 leaflet.css）。用 bundler 时直接 import ‘leaflet/styles.css’;；CDN 则用对应版本的 link。
- 创建实例。2.0 推荐写法：const map = new LeafletMap(‘map’).setView([51.505, -0.09], 13); 或一次性传 options：new LeafletMap(‘map’, {center: [51.505, -0.09], zoom: 13});。1.9.4 则是 L.map(‘map’, {center: […], zoom: 13})。
- 立刻添加至少一个 TileLayer（例如 OpenStreetMap），否则只会看到灰色底图。生产环境务必保留 attribution，并遵守瓦片服务的使用政策。
- 验收：页面刷新后应看到瓦片正常加载、滚轮可缩放、拖动能平移，控制台无 “Map container not found” 或 “already initialized” 报错。
坐标顺序始终是 [纬度, 经度]（即 lat, lng）。默认 CRS 是 EPSG:3857（Web 墨卡托），不要轻易改动，否则瓦片会对不齐。
初始化选项与常用视图控制方法怎么选
构造时能设的选项和控制视图的方法是两套东西：前者决定“出生状态”，后者决定“运行中怎么动”。下面表格列出最常用、也最容易踩坑的部分（2.0 与 1.9.4 语义基本一致）。
| 类别 | 名称 | 作用与典型取值 | 注意点 |
|---|---|---|---|
| 初始状态 | center / zoom | 中心点 LatLng 与初始缩放级别 | 两者可在 options 里写，也可用 setView 补设 |
| 限制 | minZoom / maxZoom | 允许的缩放范围；未设时取图层极值 | 动态改用 setMinZoom / setMaxZoom |
| 限制 | maxBounds / maxBoundsViscosity | 限制可拖范围；viscosity 0~1 控制回弹阻力 | 用 setMaxBounds 可随时更新 |
| 缩放行为 | zoomSnap / zoomDelta | 默认 1（整数级）；设 0.5/0.1/0 开分数缩放 | 分数缩放适合精细制图，但瓦片可能模糊 |
| 视图方法 | setView(center, zoom?, options?) | 同时改中心和缩放，可带动画 | 最常用；返回 this |
| 视图方法 | fitBounds(bounds, options?) | 自动算最大合适缩放以框住范围 | 配合 padding 避开侧边栏；大范围后记得 invalidateSize |
| 视图方法 | flyTo / flyToBounds | 平滑飞行动画到目标 | duration、easeLinearity 可调 |
| 尺寸 | invalidateSize(options?) | 容器大小变化后强制重算 | tab、modal、侧边栏展开后必调 |
FitBoundsOptions 里常用 padding（或 paddingTopLeft / paddingBottomRight，单位像素，如 [50, 50]）和 maxZoom。ZoomPanOptions 里有 animate、duration、noMoveStart 等。获取当前状态用 getCenter()、getZoom()、getBounds()、getSize() 即可。
缩放级别原理很直观：zoom 0 大约是整世界落在 256×256 像素瓦片上，每加一级宽高翻倍（256 × 2^zoom）。ScaleControl 显示的是中心点附近的比例尺，圆柱投影下并非处处等距。
容器尺寸变化与边界控制要注意什么
GIS 页面里地图经常藏在标签页、抽屉或响应式布局里。容器从 display:none 变成可见、或窗口 resize 后，如果不调用 map.invalidateSize()，会出现灰边、瓦片错位或中心偏移。trackResize 默认是 true，能自动处理普通窗口缩放，但程序化改变容器尺寸时仍需手动 invalidate。
- 限制用户拖出感兴趣区域：初始化时设 maxBounds，或运行中 map.setMaxBounds(bounds)。viscosity 接近 1 时拖拽会有明显阻尼。
- 让地图刚好框住一组要素：先算出 LatLngBounds，再 map.fitBounds(bounds, {padding: [40, 40], maxZoom: 16})。
- 需要平滑过渡时优先 flyTo / flyToBounds；需要立刻到位且避免动画卡顿时设 animate: false。
- 定位用户位置：map.locate({setView: true, maxZoom: 16})，必须在 HTTPS 下使用；失败时可回退到 fitWorld()。
CRS 默认 EPSG:3857 已经和绝大多数在线瓦片对齐。除非你明确要做等距投影或自定义坐标系，否则不要改 crs 选项。
常见问题
为什么报 “Map container not found”？
容器 div 在构造函数执行时还不在 DOM 里。把脚本放在容器后面，或确认模块脚本在页面解析完成后再跑；用 getElementById 检查元素是否存在即可。
为什么报 “Map container is already initialized”？
同一容器被初始化了两次，常见于 SPA 重新渲染或 React StrictMode。先调用 map.remove()（必要时再 off 事件），再重建；或保证组件用唯一 key 强制销毁旧实例。
地图一片灰、瓦片不出来怎么办？
通常是没加 TileLayer、容器高度为 0、或 CSS 把 img 限制死了。补上图层、给容器写死高度、覆盖冲突样式；若地图曾在隐藏容器里，显示后立刻 map.invalidateSize()。
fitBounds 后视图不准或动画卡住？
确认传入的是有效 LatLngBounds；容器刚 resize 过要先 invalidateSize；大范围或浮点误差时可暂时关掉动画（animate: false）并加 padding。部分历史边界计算问题已在早期版本修复，可参考相关讨论 Leaflet issue 6353 与 issue 2493。
初始化时把容器高度、CSS、唯一实例和至少一个 TileLayer 一次做对，再用 setView / fitBounds / invalidateSize 控制视图，就能覆盖绝大多数日常需求。新项目优先跟官方文档用 2.0.0-beta.2 的 LeafletMap 写法；维护旧代码则继续用 1.9.4 的 L.map，两者视图 API 几乎可直接对照迁移。建议先写一个最小可运行示例验证容器与图层，再叠加 maxBounds 与 padding，验收标准就是：刷新后瓦片清晰、缩放平移流畅、隐藏再显示后视图不偏移。