Leaflet 1.5.1 热修复版深度解读模块导出回归的根因、修复与升级指南【免费下载链接】Leaflet JavaScript library for mobile-friendly interactive maps 项目地址: https://gitcode.com/gh_mirrors/le/LeafletLeaflet 1.5.1 是 2019 年 5 月 8 日与 1.5.0 同日发布的紧急热修复hotfix版本其唯一使命是修复 1.5.0 引入的模块导出module export回归问题。本文将结合本仓库的发布公告、CHANGELOG.md 与 git 历史提交还原这次回归的来龙去脉说明 1.5.0 带来了哪些新特性、1.5.1 具体修复了什么、普通使用者如何升级并对照当前仓库源码讲解 Leaflet 现代版本中 ES 模块导出的构建方式与验证方法帮助你规避同类构建工具升级引发运行时回归的坑。发布背景一天之内的两个版本Leaflet 1.5.0 与 1.5.1 均发布于 2019 年 5 月 8 日。原文档的公告docs/_posts/2019-05-08-leaflet-1.5.1.md明确指出Leaflet 1.5.1 is out! This is a hotfix release, which fixes module export regression in 1.5.0.也就是说1.5.1 并非功能迭代版本而是针对 1.5.0 发布当天暴露出的严重问题所做的紧急修复。对于生产项目而言当天发布、当天修复本身就说明了该回归对使用模块化构建流程如 webpack、Rollup的用户影响面之广。1.5.0 引入的新特性1.5.1 完整继承虽然 1.5.0 存在回归但它本身是一个功能丰富的版本。CHANGELOG.md 记录了 1.5.0 的主要变更这些能力在升级到 1.5.1 后可以放心使用API 新增VideoOverlay新增keepAspectRatio选项#6038控制视频覆盖层是否保持原始宽高比Map 新增对keydown/keyup事件的支持#6421让地图可以响应键盘输入Marker新增shadowPane选项#6460可将阴影图标放入独立的地图窗格pane中新增L.SVGOverlay类#6517用于在固定地理边界上叠加任意 SVG 内容Marker新增getIcon方法#6457便于获取标记当前使用的图标实例。改进与修复属性attribution链接升级为 HTTPS#6593DivIcon的html选项现在可以直接接受 DOM Element#6571微优化了GeoJSON._setLayerStyle#6616并复用了openPopup/openTooltip的代码#6613修复了多地图场景下Control.Layers单选按钮、Canvas 折线 mouseover 行为、L.Util.formatNum精度等一系列问题。核心修复1.5.0 的模块导出回归回归是什么1.5.0 的构建产物在 ES 模块ESM导出环节出现问题导致通过打包器或原生 ESM 方式importLeaflet 的用户可能拿到异常的导出内容。这正是模块导出回归module export regression的含义——它不影响直接通过script引入全局L对象的传统用法但会破坏基于模块化的现代前端工程。根因Rollup 构建工具链的版本问题CHANGELOG.md 中 1.5.1 的条目只有一行## 1.5.1 (2019-05-08) * Fix module export regression (#6647) by cherniavskii要弄清修复了什么需要深入 git 历史。仓库中对应提交 c3105cac 的提交信息为lock rollup version (#6647)其变更内容非常直白package.json将rollup从^1.11.0锁定为精确版本0.51.8package.json将karma-rollup-preprocessor从^7.0.0回退为^5.0.1该包用于在 Karma 测试中预编译源码与 Rollup 版本强耦合spec/karma.conf.js同步回退相关配置。由此可见从提交信息与依赖变更可以推断1.5.0 发布时构建使用的 Rollup 1.x 对 ES 模块输出尤其是export * from ...这类命名空间再导出的处理发生了变化导致生成的leaflet-src.js等模块化产物导出异常1.5.1 通过把 Rollup 钉死在旧版 0.51.8 快速止血使模块导出恢复正确。这类问题的经典之处在于库的源码本身没有变化坏的是构建工具链。回归往往不是逻辑错误而是上游构建器升级后输出语义改变这提醒库维护者应在发布流程中锁定或严格管控构建工具版本。影响面与验证受影响用户通过 npm/yarn 安装 Leaflet 并在 webpack、Rollup、Parcel 等打包器中使用 ESM 导入或直接使用script typemodule的用户不受影响用户通过script srcdist/leaflet.js或 CDN 以全局L方式使用的用户验证方式升级到 1.5.1 后检查import * as L from leaflet或import {Map, TileLayer} from leaflet的命名导出是否与文档一致即可确认修复生效。如何升级到 1.5.1原文档给出的获取方式有两条路径同样适用于今天回顾这个版本包管理器更新依赖对于 npm 项目将 package.json 中的 leaflet 依赖更新到 1.5.1 后重新安装# npm npm install leaflet1.5.1 # yarn yarn add leaflet1.5.1下载页面从官方下载页获取对应版本的文件本仓库对应页面为 docs/download.md。另外与本次发布同步的还有文档体系调整git 提交 80edb4e91.5.1 (#6648)一并更新了docs/_config.yml、docs/download.md、docs/index.html并新增了指向 1.5.0 的文档重定向页保证 API 参考文档与最新稳定版一致。仓库中的 docs/reference-versions.html 即用于维护各历史版本的参考文档索引。完整的发布流程可以查阅 RELEASE.md。从历史到现状现代 Leaflet 的模块导出体系作为对照当前仓库的 Leaflet 已演进为 ESM 优先的构建体系理解它有助于你从根上理解模块导出这个话题package.json 声明type: module并通过exports字段把主入口指向./dist/leaflet-src.js源码级 ESM 产物./styles.css指向样式文件src/Leaflet.js 是模块的单一入口通过export const version pkg.version和若干export * from ./xxx/index.js语句把控制、核心、DOM、几何、地理、图层、地图等子模块统一再导出——这正是当年 Rollup 1.x 处理起来出问题的语法形态build/rollup-config.js 展示了现代版本的多格式输出策略同一份源码同时产出dist/leaflet-src.jsESM、dist/leaflet.jsESM 压缩版、dist/leaflet-global-src.js/dist/leaflet-global.jsUMD 全局变量L版本含noConflict支持并内联 banner 与 sourcemap仓库内的 debug/tests/dist-esm.html 提供了原生 ESM 的实测页面它通过 import map 将leaflet映射到../../dist/leaflet-src.js然后import {LeafletMap, TileLayer} from leaflet创建地图。这类调试页正是验证模块导出是否正确的最直接手段——当年 1.5.0 的回归正是这类基于 ESM 的使用方式最先暴露问题。对比可见1.5.1 时代 Leaflet 还需要靠锁定旧 Rollup 来保证导出正确而现在的仓库已经采用 Rollup 4.x并把 ESM 作为一等公民输出同时保留 UMD 全局版本兼容传统用法。经验小结构建工具锁版本是发布纪律1.5.1 的教训是库本身没变构建器升级导致产物语义变化。对于发布产物的开源库建议对构建链采用精确版本锁定并加入导出正确性的回归测试。热修复要快、要窄1.5.1 在 1.5.0 发布当天完成修复改动面仅限于构建依赖最大程度降低了二次回归风险。模块化使用者的自查路径若升级库版本后出现导出为空 / undefined / 命名导入异常优先对比库的构建产物与入口文件如本仓库的 src/Leaflet.js再用仓库自带的 ESM 调试页debug/tests/dist-esm.html复现验证。如需查阅完整变更记录可以继续阅读仓库根目录的 CHANGELOG.md各历史版本的 API 参考文档可通过 docs/reference-versions.html 跳转。【免费下载链接】Leaflet JavaScript library for mobile-friendly interactive maps 项目地址: https://gitcode.com/gh_mirrors/le/Leaflet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考