Leaflet 安装与项目引入方法
Leaflet 安装可通过 npm、CDN 或本地下载完成。截至 2026 年 11 月，npm 默认仍安装稳定版 1.9.4，适合现有插件与生产环境；若要试用新特性可安装 2.0.0-beta.2。引入时必须同时加载 CSS，并为地图容器设置明确高度，否则会出现空白或灰色底图。新项目可按构建工具选择 ES 模块写法，旧代码则优先保留 1.x 全局脚本方式。
如何选择 1.9.4 还是 2.0 beta
版本选择直接决定 API 写法与插件兼容性。生产环境、大量旧插件、需兼容较老浏览器时，继续使用 1.9.4；新项目且目标浏览器为 Baseline 2022（Safari 15.4+ 等 evergreen）时，可试用 2.0 beta。2.0 改为纯 ES classes、内置 TypeScript 类型、默认 marker 使用 inline SVG，并移除了 IE 与 AMD/CommonJS 支持。
| 版本 | 状态（截至 2026-11） | 推荐安装命令 | 主要差异 |
|---|---|---|---|
| 1.9.4 | 稳定（2023-05 发布） | npm install leaflet | 全局 L.map 工厂方法；需处理默认图标路径；插件生态最全 |
| 2.0.0-beta.2 | 预发布（2026-11-06） | npm install leaflet@beta | new LeafletMap；tree-shakeable；无 images 依赖；部分旧插件需适配 |
从 1.x 升级前务必阅读官方1.x 到 2.0 迁移指南，工厂方法、事件命名、嵌套类名等都有破坏性变更。最新 beta 细节见v2.0.0-beta.2 发布说明。
用 npm 安装并引入（推荐 Vite / 打包工具）
现代前端项目优先用 npm，便于 tree-shaking 与类型提示。2.0 包内已含 TypeScript 定义，无需再装 @types/leaflet。
- 安装稳定版：npm install leaflet；安装当前 beta：npm install leaflet@beta（或指定 leaflet@2.0.0-beta.2）。
- 在入口文件或组件中引入样式与模块。2.0 示例：import { LeafletMap, TileLayer } from ‘leaflet’; import ‘leaflet/styles.css’;。1.9.4 仍常用 import L from ‘leaflet’; import ‘leaflet/dist/leaflet.css’;。
- 创建地图容器并设置高度，例如 <div id=”map” style=”height:400px”></div>。百分比高度时，父元素也必须有明确高度。
- 初始化。2.0：const map = new LeafletMap(‘map’).setView([39.9, 116.4], 10); new TileLayer(‘https://tile.openstreetmap.org/{z}/{x}/{y}.png’).addTo(map);。1.9.4：L.map(‘map’).setView(…); L.tileLayer(…).addTo(map);。
- 本地开发时用 Vite、webpack 等启动；纯静态文件请用本地 HTTP 服务（npx serve 或 python -m http.server），浏览器不允许 file:// 加载 ES modules。
验收标准：页面出现可缩放的底图、无控制台 404（尤其是图标与 CSS）、拖拽与缩放正常。容器尺寸变化后调用 map.invalidateSize()。
CDN 与本地下载引入方式
无构建步骤或快速原型时用 CDN；内网或需离线时下载 zip。推荐保留 integrity 校验。
- 2.0 CDN + import map：在 head 引入 leaflet.css，再写 importmap 指向 leaflet.js，然后在 type=”module” 脚本中 import { LeafletMap, TileLayer } from ‘leaflet’。
- 2.0 全局脚本（兼容旧写法）：引入 leaflet-global.js，使用 new L.LeafletMap(…)；已不再支持 L.noConflict() 与 AMD。
- 1.9.4 CDN：直接 link leaflet.css 并 script leaflet.js，使用熟悉的 L.map / L.tileLayer。
- 本地下载：从 GitHub Releases 下载对应版本的 leaflet.zip，解压后放到站点静态目录，按相对路径更新 CSS 与 script/importmap。zip 含 leaflet.js、leaflet-global.js、leaflet.css 与 source map；2.0 的 CSS 不再依赖额外 images 文件夹。
注意：许多旧插件尚未适配 2.0，可先在插件页确认 “Ready for Leaflet 2” 或暂时锁定 1.9.4。从源码构建需克隆仓库后执行 npm install 与 npm run build，输出位于 dist。
安装后必做检查与常见踩坑
安装本身很少失败，问题几乎都出在引入与容器配置上。
- 地图灰色或空白：容器高度为 0（常见于 height:100% 但父链未设高度）。改为固定 px 或保证父元素有高度。
- 瓦片错位、控件无样式：忘记加载 CSS。npm 用 styles.css / leaflet.css，CDN 必须同步 link。
- 1.x 默认 marker 图标 404：打包工具改写了图片路径。手动 mergeOptions 指定 iconUrl 等，或换用兼容插件；2.0 已改为 inline SVG，旧 workaround 反而会出错。
- 模块脚本报 CORS / 加载失败：用本地 HTTP 服务打开，不要双击 HTML。
- 2.0 下旧代码报错：L.map 等工厂方法已移除，事件改为 pointer*，部分 Util 方法删除。对照迁移指南逐项改写。
浏览器要求：1.9.4 仍支持 IE9–11；2.0 仅 evergreen，依赖 Pointer Events 与 ES modules。无外部运行时依赖，许可证为 BSD-2-Clause。
常见问题
npm install leaflet 装到的是哪一版？
截至 2026 年 11 月，latest 标签仍是 1.9.4。要装 2.0 请显式使用 leaflet@beta 或 leaflet@2.0.0-beta.2，安装后用 npm list leaflet 确认版本号。
为什么本地双击 HTML 看不到地图？
ES modules 受浏览器安全限制，不能从 file:// 协议加载。用 npx serve、Live Server 或 python -m http.server 起一个本地服务再访问。
2.0 还能用以前的 L.markercluster 等插件吗？
多数旧插件尚未完全适配。先查插件是否标注支持 Leaflet 2，或暂时停留在 1.9.4；部分热门插件已有 2.0 beta 分支可试用。
地图容器高度设了 100% 还是不显示怎么办？
百分比高度要求从 html/body 到父元素整条链都有高度。最稳妥是先给容器写死 height: 400px 或 50vh，确认能显示后再改布局，并在 resize 后调用 invalidateSize()。
总结：日常与生产优先 npm 安装 1.9.4 并正确引入 CSS；新项目在确认浏览器与插件后再试 2.0 beta。动手前先给地图容器设明确高度，引入后立刻用简单 setView + TileLayer 做验收，能放大缩小且无控制台报错即安装成功。