Leaflet 下载与安装:CDN 与 npm 用法
截至 2026 年 11 月,Leaflet 下载与安装最直接的方式是选用稳定版 1.9.4(兼容旧插件)或 2.0.0-beta.2(ES 模块现代化重写),通过 CDN 在页面里引入 CSS/JS,或用 npm 安装后按命名方式导入。两者均无外部依赖,gzip 后 JS 约 40 KB、CSS 约 2.4 KB,地图容器只需设定明确高度即可显示。新项目优先 2.0 beta,旧项目或大量依赖 1.x 插件时继续用 1.9.4。

怎么选版本:1.9.4 还是 2.0 beta
选择前先确认浏览器支持与插件需求。1.9.4 是最后一个 1.x 稳定版,发布于 2023 年 5 月 18 日,覆盖 Chrome、Firefox、Safari 5+、IE 9–11 等;2.0.0-beta.2 发布于 2026 年 11 月 6 日(beta.1 为 11 月 2 日),仅支持 Baseline 2022(Safari 15.4+),不再兼容 IE。2.0 默认标记改为内联 SVG、完整 tree-shaking、内置 TypeScript 类型,体积在按需导入后可进一步缩小(例如地图+瓦片层约 25.6 KB)。许多 1.x 插件尚未适配,需查看是否标注 Ready for Leaflet 2。
| 对比项 | 1.9.4(稳定) | 2.0.0-beta.2 |
|---|---|---|
| 默认安装命令 | npm install leaflet | npm install leaflet@2.0.0-beta.2 或 @beta |
| 模块形式 | UMD/全局 L,有默认导出 | 纯 ES 模块,命名导入,无默认导出 |
| 标记图标 | 需 images 文件夹,bundler 易路径出错 | 内联 SVG,可直接设颜色与旋转 |
| 适用场景 | 旧插件多、需兼容老浏览器 | 新项目、Vite/现代打包、要 TypeScript |
开发快照可从 GitHub main 分支获取,但可能含未发布的破坏性更改,生产环境不建议。更详细的迁移说明可参考 Leaflet 2.0 相关 Pull Request。
CDN 用法:最快上手的步骤
CDN 适合静态页面或快速验证。常用源为 jsDelivr、unpkg、cdnjs,建议加上 integrity 哈希。2.0 推荐配合 importmap;1.9.4 则用经典 script 标签即可。
- 在 <head> 引入对应版本的 leaflet.css(必须,否则地图控件样式缺失)。
- 按版本选择脚本引入方式:2.0 用 importmap + type=”module”;1.9.4 直接 script src。
- 页面放一个带明确高度的容器,例如 <div id=”map” style=”height:400px”></div>。
- 在 DOM 就绪后初始化地图(2.0 用 new LeafletMap,1.9 用 L.map)。
- 本地用 file:// 打开 2.0 模块脚本会失败,请先起本地服务器(npx serve 或 python3 -m http.server)。
2.0.0-beta.2 推荐写法(带 integrity):先写 stylesheet 指向 cdn.jsdelivr.net/npm/leaflet@2.0.0-beta.2/dist/leaflet.css(哈希 sha256-wxn0bvASs4VWLkNdZLbtMJxJSk7hbXmj96XO2R0y0bk=),再写 importmap 把 “leaflet” 映射到同版本的 leaflet.js(哈希 sha256-6inY4DmZyVCdH2vZdiOfWSG8DJyavmOjc4WZgu15j9E=),最后用 <script type=”module”> import {LeafletMap, TileLayer} from ‘leaflet’; …</script>。若仍想用全局 L,可改为引入 leaflet-global.js(哈希 sha256-8NZyazzrmaQXhtk/LXGmOpSO6zW1v4TcWNOemoEE3IY=),然后 new L.LeafletMap(…)。
1.9.4 更简单:stylesheet 指向 leaflet@1.9.4/dist/leaflet.css(哈希 sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=),script 指向 leaflet.js(哈希 sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=),之后直接使用全局 L。

npm 安装与现代打包用法
适合 Vite、Webpack、Rollup 等项目。安装后文件位于 node_modules/leaflet/dist。
- 执行 npm install leaflet(默认拿到 1.9.4)或 npm install leaflet@2.0.0-beta.2。
- 在入口文件导入:2.0 写 import {LeafletMap, TileLayer} from ‘leaflet’; import ‘leaflet/styles.css’;(或 leaflet/dist/leaflet.css)。1.x 仍可用 import L from ‘leaflet’; import ‘leaflet/dist/leaflet.css’;。2.0 无默认导出,也可用 import * as L from ‘leaflet’。
- 2.0 已内置 TypeScript 类型,不必再装 @types/leaflet。
- 确保打包器正确处理 CSS;地图初始化放在容器已挂载之后。
- 自源码构建:克隆仓库后 npm install && npm run build,产物在 dist。
1.x 在 bundler 下常见默认图标路径被重写导致破损,需手动 mergeOptions 或借助兼容插件;2.0 用 SVG 后该问题已消失,旧 workaround 可删除。官方文档源可对照 Leaflet 文档源文件。
自托管下载与配置注意点
不想依赖 CDN 时,从 GitHub releases 下载对应版本的 leaflet.zip。2.0 zip 含 leaflet.js(ES 模块压缩版)、leaflet-global.js、leaflet.css(无 images 文件夹)及 .map;1.9 zip 含 leaflet.js、leaflet-src.js、leaflet.css 和 images 文件夹(必须与 CSS 同目录)。解压后放到站点静态目录,用相对路径引用即可。
- CSS 必须加载,否则缩放按钮、图层控件样式全无。
- 地图 div 高度不能为 0 或 auto,常见写法 height: 400px 或 100vh。
- 瓦片图层记得加 attribution,符合服务商要求。
- 2.0 工厂函数改为构造函数(L.map → new LeafletMap),嵌套类扁平化(Control.Zoom → ZoomControl,Icon.Default → DefaultIcon),旧写法会报错或警告。
验收标准:页面刷新后出现可缩放的底图,控制台无 404 或模块加载错误,默认标记正常显示(2.0 可直接设 color)。
常见问题
用 npm 装完 1.x 后标记图标是破的怎么办?
bundler 改写了 CSS 里的图片 URL。手动设置 L.Icon.Default.mergeOptions 指向正确的 iconUrl、iconRetinaUrl、shadowUrl,或改用 CDN 加载 CSS;升级到 2.0 后该问题因 SVG 标记彻底消失。
2.0 模块脚本在本地双击 HTML 打不开?
浏览器安全策略禁止 file:// 加载 ES 模块。用 npx serve 或 python3 -m http.server 起一个本地 HTTP 服务再访问。
从 1.9 迁到 2.0 代码全报错?
主要破坏性变更:必须用 new 构造、命名导入、类名扁平化,部分旧 API 已移除。逐条对照官方迁移说明修改,并确认所用插件是否已支持 Leaflet 2。
地图容器是空白的?
最常见原因是没引入 CSS,或 div 高度为 0。检查 network 面板确认 leaflet.css 返回 200,并给容器写死高度后再初始化。
总结:新项目直接上 2.0.0-beta.2 的 CDN importmap 或 npm 命名导入,旧项目继续钉死 1.9.4 并注意图标路径。无论哪种方式,先保证 CSS 与容器高度正确,再加底图与标记;验收时看控制台零报错、地图可交互即可。建议先用 CDN 验证最小示例,再迁到 npm 打包流程。