构建与开发

本页提供 Leaflet 开发环境、构建系统、测试框架和开发工作流的概述。它涵盖了贡献者构建 Leaflet 或从源代码构建所需的基本工具、流程和命令。

关于 CI/CD 流水线和自动化工作流的详细信息，请参阅构建系统与 CI/CD。关于贡献指南和代码风格要求，请参阅贡献指南。

开发环境搭建

Leaflet 需要 Node.js（CI 中使用版本 24）和 npm 进行开发。构建系统使用现代 ES 模块，除了 Node.js 外不需要额外的全局工具。

初始设置

# 克隆仓库
git clone https://github.com/Leaflet/Leaflet.git
cd Leaflet

# 安装依赖
npm install

# 构建库
npm run build

关键依赖

依赖	用途	配置
`rollup`	JavaScript 打包器	build/rollup-config.js1-75
`eslint`	代码检查	eslint.config.js1-126
`karma`	测试运行器	package.json19-30
`mocha` + `chai`	测试框架	package.json17-28
`terser`	代码压缩	package.json10
`leafdoc`	API 文档	package.json26

源代码组织

Leaflet 源代码在 src/ 目录下组织成模块化结构，每个主要子系统位于其自己的子目录中。

100%

模块入口点

主入口点 src/Leaflet.js1-24 从子目录重新导出所有公共 API：

control/ - UI 控件（缩放、归属、图层）
core/ - 基类（Class、Evented、Util）
dom/ - DOM 工具和事件处理
geometry/ - 几何基元（Point、Bounds、Transformation）
geo/ - 地理基元（LatLng、LatLngBounds、CRS）
layer/ - 所有图层类型（瓦片、矢量、标记等）
map/ - Map 类和处理器

构建流程概述

Leaflet 使用 Rollup 作为其打包器，从 ES 模块源代码创建多种输出格式。构建过程生成四个 JavaScript 包以及 CSS 和图像资源。

构建配置

Rollup 配置 build/rollup-config.js1-75 定义：

输入： build/rollup-config.js51

input: './src/Leaflet.js'

输出格式：

文件	格式	特性	用途
`dist/leaflet-src.js`	ESM	Sourcemap, 未压缩	开发（NPM 主导出）
`dist/leaflet.js`	ESM	压缩, sourcemap	生产 ESM
`dist/leaflet-global-src.js`	UMD	全局 `L`, sourcemap	开发（浏览器）
`dist/leaflet-global.js`	UMD	全局 `L`, 压缩	生产（CDN）

静态资源：

staticAssetsPlugin build/rollup-config.js16-24 将这些文件复制到 dist/：

leaflet.css
images/logo.svg
images/layers.svg
images/marker-icon.svg
images/marker-shadow.svg

NPM 脚本

100%

关键命令：

npm run build - 构建所有输出包 package.json54
npm run watch - 文件更改时重新构建 package.json55
npm test - 在 Chrome headless 中运行测试 package.json52
npm run coverage - 生成覆盖率报告 package.json53
npm run lint - 检查代码风格 package.json56
npm run lintfix - 自动修复检查问题 package.json57
npm run docs - 生成 API 文档 package.json51
npm run debug - 启动本地 HTTP 服务器 package.json50

测试框架

Leaflet 使用 Karma 作为测试运行器，Mocha 作为测试框架，Chai 用于断言。测试位于 spec/ 目录中。

测试执行流程

100%

浏览器测试

测试通过 Karma 启动器在多个浏览器中运行 package.json20-29：

Chrome / ChromeHeadless（默认）
Firefox / FirefoxHeadless
FirefoxRetina（devicePixelRatio=2 的 Firefox）
SafariNative（仅 macOS）

运行测试：

# 默认（Chrome headless）
npm test

# 特定浏览器
npm test -- --browsers Firefox

# 带覆盖率
npm run coverage

# 持续运行（监听模式）
npm test -- --no-single-run

服务端渲染测试

Leaflet 在 Node.js 和 Deno 环境中验证 SSR 兼容性 .github/workflows/main.yml94-121：

spec/ssr/ssr_node.js - Node.js SSR 测试
spec/ssr/ssr_deno.js - Deno SSR 测试

开发工作流

典型的开发工作流涉及更改源文件、在监听模式下运行构建，以及在浏览器中测试。

交互式开发循环

100%

监听模式开发

对于活跃开发，使用监听模式 CONTRIBUTING.md113-118：

启动构建监听：npm run watch
在 debug/ 目录中打开调试页面
在 src/ 中编辑源文件
重新加载浏览器查看更改

调试页面自动加载带 sourcemap 的 dist/leaflet-src.js，使调试变得简单。

Git 预提交钩子

Leaflet 使用 Husky 在提交前自动运行检查 package.json60：

# 通过 husky 配置
npm run lint  # 在 git commit 时自动运行

跳过钩子（用于 WIP 提交）：

git commit -m "WIP" --no-verify

质量保证

Leaflet 通过多个在本地和 CI 中运行的自动化检查来强制执行代码质量。

检查配置

ESLint 使用 eslint.config.js1-126 强制执行代码风格：

配置	用途
`eslint-config-mourner`	基础代码风格
`@eslint/css`	CSS 检查
`eslint-plugin-import-x`	ES 模块导入
`eslint-plugin-baseline-js`	浏览器兼容性
`@mapbox/eslint-plugin-script-tags`	Markdown 代码块

关键规则：

缩进使用制表符 eslint.config.js43
强制使用花括号 eslint.config.js37
ES 模块需要扩展名 eslint.config.js41
浏览器基线：广泛可用的 API eslint.config.js84-91

包大小监控

Bundlemon .bundlemonrc.json1-24 强制执行大小限制：

文件	最大大小（gzip）
`dist/leaflet.js`	40 KB
`dist/leaflet.css`	3.2 KB

包大小检查在 CI 中运行 .github/workflows/main.yml70-93 并在 Pull Request 上报告状态。

完整性哈希生成

build/integrity.js 脚本 build/integrity.js1-38 为 CDN 分发生成 SHA-256 完整性哈希：

npm run docs  # 生成文档 AND 更新完整性哈希

这会更新 docs/_config.yml 中以下文件的哈希：

leaflet.js
leaflet-src.js
leaflet-global.js
leaflet-global-src.js
leaflet.css

包分发

Leaflet 通过多个渠道分发，每个渠道有特定的文件格式。

NPM 包

包 package.json37-44 导出：

{
  "exports": {
    ".": "./dist/leaflet-src.js",
    "./styles.css": "./dist/leaflet.css"
  },
  "type": "module"
}

包含的文件： package.json42-48

dist/ - 构建文件
src/ - 源代码
CHANGELOG.md

安装：

npm install leaflet

导入：

import * as L from 'leaflet';
import 'leaflet/styles.css';

CDN 分发

UMD 构建（leaflet-global.js 和 leaflet-global-src.js）通过 jsDelivr 优化用于 CDN，带有完整性哈希用于子资源完整性（SRI）验证。

GitHub Releases

CI 自动将开发快照发布到 GitHub Releases .github/workflows/main.yml164-191：

标签：dev
包括 dist/leaflet.zip，包含所有构建文件

开发环境矩阵

Leaflet 在多个操作系统和浏览器上进行测试以确保兼容性。

CI 环境矩阵

操作系统	测试的浏览器
Ubuntu	Chrome, Firefox, Firefox (Retina)
macOS	Chrome, SafariNative
Windows	Chrome

所有平台使用 Node.js 24 .github/workflows/main.yml6

必需工具

工具	用途	版本
Node.js	构建系统	24
npm	包管理器	（与 Node 捆绑）
Ruby	文档服务器	参见 `docs/.ruby-version`
Chrome/Firefox	测试	最新

矢量图层

构建与开发

开发环境搭建

初始设置

关键依赖

源代码组织

模块入口点

构建流程概述

构建配置

NPM 脚本

测试框架

测试执行流程

浏览器测试

服务端渲染测试

开发工作流

交互式开发循环

监听模式开发

Git 预提交钩子

质量保证

检查配置

包大小监控

完整性哈希生成

包分发

NPM 包

CDN 分发

GitHub Releases

开发环境矩阵

CI 环境矩阵

必需工具

相关文档

构建与开发 ​

开发环境搭建 ​

初始设置 ​

关键依赖 ​

源代码组织 ​

模块入口点 ​

构建流程概述 ​

构建配置 ​

NPM 脚本 ​

测试框架 ​

测试执行流程 ​

浏览器测试 ​

服务端渲染测试 ​

开发工作流 ​

交互式开发循环 ​

监听模式开发 ​

Git 预提交钩子 ​

质量保证 ​

检查配置 ​

包大小监控 ​

完整性哈希生成 ​

包分发 ​

NPM 包 ​

CDN 分发 ​

GitHub Releases ​

开发环境矩阵 ​

CI 环境矩阵 ​

必需工具 ​

相关文档 ​

构建与开发

开发环境搭建

初始设置

关键依赖

源代码组织

模块入口点

构建流程概述

构建配置

NPM 脚本

测试框架

测试执行流程

浏览器测试

服务端渲染测试

开发工作流

交互式开发循环

监听模式开发

Git 预提交钩子

质量保证

检查配置

包大小监控

完整性哈希生成

包分发

NPM 包

CDN 分发

GitHub Releases

开发环境矩阵

CI 环境矩阵

必需工具

相关文档