Leaflet 版本发布全解从 CHANGELOG 到 NPM 发布的完整流程与文档更新机制【免费下载链接】Leaflet JavaScript library for mobile-friendly interactive maps 项目地址: https://gitcode.com/gh_mirrors/le/Leaflet本文以 Leaflet 仓库根目录的发布手册 RELEASE.md 为主体完整解析 Leaflet 新版本patch/minor/major从发布前检查、版本号提升、CI 自动化发布到发布后文档站点更新的端到端流程。读完本文你可以复现一次规范的 Leaflet 版本发布并理解npm version打的 tag 如何驱动 GitHub Actions 完成 NPM 发布、构建产物integrity hash如何自动生成并回写文档配置避免发布遗漏。1. 发布前的准备工作Pre-release ChecklistRELEASE.md 将一次版本发布拆成“发布动作”与“发布后文档更新”两个阶段。第一阶段的前置检查依次是清空 blocker确保所有标记为 blocker 的 issue 和 pull request 已解决。这是版本冻结的第一道门槛——带阻塞性缺陷的版本不应流出。更新 CHANGELOG 并提交自上一个版本发布以来维护 CHANGELOG.md 的新增条目并提交。Leaflet 的 changelog 有明确的组织规范从 CHANGELOG.md 可见每个版本条目下按固定小节归类❇️ New Features新功能✨ Refactorings (⚠️ Breaking Changes)破坏性重构❌ Removed Features (⚠️ Breaking Changes)被移除的特性 Bugfixes缺陷修复每条变更记录都标注了贡献者与 PR 编号例如 2.0.0-alpha.1 中的 New exportLeafletMapas an alias forMap 和 Drop aliased functions … on Evented。这条 checklist 要求的是changelog 先于npm version更新因为版本号提升后会立即触发 tag 与 CI 发布流程事后补 changelog 会混入发布提交之后的条目边界。确认 CI 全绿在继续之前确保当前main分支上所有测试通过。当前 CI 定义在 .github/workflows/main.yml包含build-docs、lint、bundlemon、test-ssr和testvitest 多浏览器矩阵chromium、firefox、chromium-retina、Windows chromium、macOS webkit且每套项目还会以VITE_TOUCH1再跑一遍触摸模式测试。2. 提升版本号npm version与 tag 推送RELEASE.md 的核心命令是npm version patch | minor | major这一步由 npm 自身完成两件事更新 package.json 中的version字段当前仓库中为2.0.0-alpha.1并写入对应package-lock.json生成一个提交并打 git tag形如v2.0.0-alpha.1但 tag 还留在本地。因此下一条 checklist 紧跟其后git push --follow-tags把 npm 创建的版本提交连同 tag 一起推到 GitHub。这里的--follow-tags是关键Leaflet 的自动化发布完全依赖tag 推送事件触发而不是提交本身。3. CI 自动完成 NPM 发布tag 驱动的publish-npm工作流推送 tag 后不需要手动执行npm publish。从 .github/workflows/main.yml 可以看到整个自动化链路on: push: branches: [main] tags: [v*]工作流在main分支推送和v*开头的 tag 推送时都会运行其中publish-npmjob 的触发条件正是 tag 推送publish-npm: if: github.repository_owner Leaflet startsWith(github.ref, refs/tags/v)它的执行序列是npm ciCI 环境固定 Node 24registry-url: https://registry.npmjs.orgnpm run build调用 build/rollup-config.js 的 rollup 配置产出dist/中的leaflet.js、leaflet-src.js、leaflet-global.js、leaflet-global-src.js、leaflet.css及 source map发布并根据 tag 名自动决定 npm dist-tagTAG$(echo $GITHUB_REF_NAME | grep -oP ^v\d\.\d\.\d-?\K(\w)?) npm publish --tag ${TAG:-latest}这段正则从v2.0.0-alpha.1这类 tag 中提取2.0.0-alpha.1之后、以.分隔之外的字母段alpha作为 npm 的--tag参数若 tag 是纯v2.0.0则无 prerelease 段回落到latest。也就是说SemVer 的 prerelease 约定-alpha.1、-beta.2等直接决定了该版本在 npm 上挂哪个 dist-tag正式版本进latest预发布版本进自己的通道互不覆盖。这与 CHANGELOG 中 2.0.0-alpha、2.0.0-alpha.1 这类预发布版本并存的现状一致。另外两个 job 也值得在发布视角下理解publish-artifacts仅main分支、仅官方仓库执行npm run build后将dist/*连同CHANGELOG.md、LICENSE、README.md压缩为leaflet.zip并以dev为 tag 名发布为 GitHub Release 的 “Development snapshot”。这正是 docs/download.md 中 “Development Snapshot / Single files” 下载行的数据来源。bundlemon对构建产物做体积基线检查防止意外增重进入主干。RELEASE.md 要求“等待 CI 完成并跟踪日志确认成功”指的就是这条publish-npm链路随后人工核对两点NPM 上leaflet包页面是否出现新版本与正确的dist文件清单jsDelivrnpm/leafletlatest/上的文件是否同步。发布包的打包边界由 package.json 的files字段决定dist、src排除dist/leaflet.zip与*.leafdoc以及CHANGELOG.md入口由exports声明为./dist/leaflet-src.js样式为./dist/leaflet.css。核对 npm 产物时可按此清单验证。最后两步是 GitHub 侧收尾在 Leaflet 的 GitHub Releases 页面创建对应版本正文写 changelog 的最重要部分从 npm registry 下载该版本的 TGZ 归档URL 模板https://registry.npmjs.org/leaflet/-/leaflet-X.X.X.tgzX.X.X替换为新版本号作为该 GitHub Release 的 “asset” 上传——保证 GitHub 上的资产与 npm 发布物逐字节一致。4. 发布后的文档更新npm run docs的两段式生成RELEASE.md 的第二阶段 “Updating docs after the release” 要求新建分支后按序完成撰写新版本博客文章并放入 docs/_posts/现有文章按YYYY-MM-DD-标题.md命名如2025-05-18-leaflet-2.0.0-alpha.mdJekyll 站点据此生成博客页将本次发布之前的reference.html存入 Internet Archive 的 Wayback Machine 快照并可选地在 docs/reference-versions.html 中追加一条指向该快照的历史版本链接运行npm run docs生成新的 docs/reference.html 并更新 docs/_config.yml 中的 integrity 哈希更新 docs/download.md 中“latest release”链接当前指向 2.0.0-alpha.1 的v2.0.0-alpha.1/leaflet.zip归档更新 docs/index.html 顶部的公告条当前内容为 “August 16, 2025 — Leaflet 2.0.0-alpha.1 has been released!”提交全部改动并提交 PR 供他人评审。其中第 3 步是整个文档体系的核心其实现链值得展开。4.1docs脚本build/docs.jsbuild/integrity.jspackage.json 中定义docs: node ./build/docs.js node ./build/integrity.js第一段 build/docs.js用leafdoc生成 API 参考页const doc new LeafDoc({ templateDir: build/leafdoc-templates, showInheritancesWhenEmpty: true, leadingCharacter: }); doc.registerDocumentable(pane, Map panes); doc.registerDocumentable(projection, Defined projections); doc.registerDocumentable(crs, Defined CRSs); doc.addFile(build/docs-index.leafdoc, false); doc.addDir(src); doc.addFile(build/docs-misc.leafdoc, false); writeFileSync(docs/reference.html, doc.outputStr());即以为文档注释前缀扫描src/全量源码含各模块下的*.leafdoc文件如 src/core/Class.leafdoc、src/map/Map.methodOptions.leafdoc套用 build/leafdoc-templates 模板输出 docs/reference.html。参考页头部会内联当前版本号This reference reflects Leaflet {{site.latest_leaflet_version}}该变量由第二段脚本回写。第二段 build/integrity.js负责 Subresource Integrity 哈希流程是从package.json读取当前版本号pkg.version请求https://cdn.jsdelivr.net/npm/leafletversion/dist/file上的五个产物leaflet.js、leaflet-src.js、leaflet-global.js、leaflet-global-src.js、leaflet.css用ssri计算 sha256正则替换 docs/_config.yml 中的六个键并落盘docConfig docConfig .replace(/latest_leaflet_version:.*/, latest_leaflet_version: ${pkg.version}) .replace(/integrity_hash_source:.*/, integrity_hash_source: ${integritySrc}) // …其余 uglified / global / css 同理当前 docs/_config.yml 中即为latest_leaflet_version: 2.0.0-alpha.1 integrity_hash_css: sha256-PhWJNlpLGBSRYC7cdsDbQH91URmpDeOzLp7DbFRtE integrity_hash_source: sha256-HmtDXNcV4omyVnB4yWuQ/EIBIAMpKS5Paajojw42NyU integrity_hash_uglified: sha256-gj5JhNAaMi6LCsjVFOk8sXDe1sWSS2Zlc87mtrLiQ integrity_hash_global_source: sha256-SnNOWrUASCy0Jw4FGryafJamqNk15qDnW00Y/biE2dU integrity_hash_global_uglified: sha256-lJUxSvvKo54k90cTx9u9DCAP1MtAEqnLmx6Sx3no03c从实现细节看一个重要的时序依赖integrity 哈希不是对本地dist/计算而是从 jsDelivr 上拉取已发布版本的文件再计算。这意味着npm run docs必须在该版本的 tag 推送、CI 完成npm publish、且 jsDelivr 缓存更新之后执行否则取到的仍是旧版本产物、哈希会错位。这也解释了为何 RELEASE.md 把它放在 “发布后” 阶段而非发布前。4.2 这些值如何被文档站点消费latest_leaflet_version与五个哈希键通过 Jekyll 的site.*全局注入docs/download.md 的 CDN 引入示例、docs/_layouts/v2.html 站点模板、docs/examples/quick-start/index.md 的示例代码以及 build/leafdoc-templates/html.hbs 参考页模板全部引用它们。因此每次发布后回写这六个键等价于一次性把整站所有示例与模板指向新版本、并刷新安全校验哈希——这也是 RELEASE.md 将 “update integrity hashes indocs/_config.yml” 与生成reference.html合并为同一步npm run docs的原因。注意本地与 CI 的分工本地npm run docs只覆盖 leafdoc 生成与哈希回写而 CI 的build-docsjob.github/workflows/main.yml执行bundle exec jekyll build --strict_front_matter以验证整个 Jekyll 站点在改动后仍能严格构建通过。5. 发布流程速查表阶段动作关键文件/证据前置清空 blocker、更新 changelog 并提交RELEASE.md、CHANGELOG.md前置确认 CIlint / 多浏览器测试 / docs 构建全绿.github/workflows/main.yml发布npm version patch\|minor\|majorpackage.json发布git push --follow-tags推送版本提交与 tag.github/workflows/main.yml发布CIpublish-npm依 tag 名自动npm publish --tag.github/workflows/main.yml发布核对 NPM / jsDelivrGitHub Release 挂载 npm TGZ 资产package.json文档博客文章入docs/_posts/、快照旧版参考页docs/_posts/、docs/reference-versions.html文档npm run docs生成参考页并回写哈希build/docs.js、build/integrity.js文档更新 download 页与首页公告提 PRdocs/download.md、docs/index.html适用前提与限制本流程针对 Leaflet 官方仓库repository_owner Leaflet的分支才执行产物/发布 job且NPM_TOKEN为仓库 secretnpm version会改写package.json/lockfile 并产生新提交fork 仓库中缺少 tag 发布权限与 CI secrets 时只能做到 changelog 与版本号准备阶段。【免费下载链接】Leaflet JavaScript library for mobile-friendly interactive maps 项目地址: https://gitcode.com/gh_mirrors/le/Leaflet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考