构建系统
本文档记录了 Mapbox GL JS 中使用的构建系统,解释了如何从源代码构建库、管理依赖关系以及导航各种构建脚本和配置。有关调试生成的代码的信息,请参阅测试和调试。
概述
Mapbox GL JS 使用以 Rollup 为中心的现代 JavaScript 构建管道。构建系统创建针对各种用例优化的不同输出格式,包括开发、生产部署和具有内容安全策略(CSP)限制的环境。
构建脚本
构建系统提供了各种 npm 脚本来处理不同的构建场景:
| Script | Description | Command |
|---|---|---|
| Development build | 带有调试信息的未压缩构建 | npm run build-dev |
| Watch mode | 文件更改时重建 | npm run watch-dev |
| Production build | 优化的未压缩构建 | npm run build-prod |
| Minified build | 优化的压缩构建 | npm run build-prod-min |
| CSP build | 符合内容安全策略 | npm run build-csp |
| CSS build | 处理 CSS 文件 | npm run build-css |
| Style spec build | 构建 style-spec 模块 | npm run build-style-spec |
| TypeScript declarations | 生成 d.ts 文件 | npm run build-dts |
| Complete build | 所有生产产物 | npm run prepublishOnly |
构建环境变量
构建脚本使用环境变量来自定义构建过程:
BUILD: 指定构建类型(dev、production、bench)MINIFY: 设置为true时启用压缩
例如,npm run build-prod-min 使用 --environment BUILD:production,MINIFY:true 运行 Rollup。
项目结构和构建输出
构建过程在 dist/ 目录中创建几个输出产物:
样式规范模块
样式规范是一个单独的模块,具有自己的构建过程。它位于 src/style-spec/ 中,既作为主库的一部分构建,也作为一个独立的包构建。
开发工作流
典型的开发工作流涉及:
- 克隆仓库
- 运行
npm install以安装依赖项 - 运行
npm run build-dev进行一次性开发构建或运行npm run watch-dev进行持续重建 - 运行
npm run build-token以生成 access token 脚本 - 运行
npm run start-server以启动本地开发服务器 - 对于完整的开发环境,运行
npm start,它结合了 token 生成、CSS 监视、JS 监视和服务器启动
代码生成
构建系统包括作为构建过程的一部分运行的代码生成脚本:
npm run codegen: 同时运行样式代码和结构数组生成器npm run build-typed-style-spec: 为样式规范生成 TypeScript 定义
这些脚本创建随后包含在构建中的源文件。
CI/CD 管道
Mapbox GL JS 使用 CircleCI 进行持续集成和部署。CI 管道包括:
CI 管道在多个平台(Linux、Mac、Windows)和浏览器(Chrome、Firefox、Safari)上构建和测试库,以确保跨平台兼容性。
依赖项
Mapbox GL JS 在 package.json 中列出了两种类型的依赖项:
- 生产依赖项: 库功能所需的依赖项
- 开发依赖项: 用于构建、测试和开发的依赖项
关键生产依赖项包括:
- 矢量瓦片处理:
@mapbox/vector-tile、pbf、vt-pbf、geojson-vt - 几何实用程序:
@mapbox/point-geometry、earcut、grid-index、potpack - 数学库:
gl-matrix、kdbush、quickselect、supercluster - 样式:
@mapbox/tiny-sdf、csscolorparser
关键开发依赖项包括:
- 构建工具:
rollup、typescript、esbuild、postcss - 测试:
vitest、playwright - Linting:
eslint、stylelint
构建自定义版本
您可以通过修改构建脚本或 Rollup 配置来创建自定义构建。最常见的方法是:
- 在
package.json中创建自定义构建脚本 - 创建自定义 Rollup 配置
- 使用环境变量自定义现有构建
示例:创建自定义构建脚本
要创建启用或禁用特定功能的自定义构建,您可以将新脚本添加到 package.json:
"scripts": {
"build-custom": "rollup -c custom-rollup.config.js"
}性能考虑
构建系统包括用于监视和提高性能的工具:
npm run check-bundle-size: 对照预定义的阈值检查包大小- 在生产构建中应用压缩以减小文件大小
- CSP 构建删除可能会被内容安全策略阻止的内联脚本
排除常见构建问题
如果在构建过程中遇到问题,请尝试以下步骤:
- 清理构建输出:
rm -rf dist - 重新安装依赖项:
rm -rf node_modules && npm install - 确保您拥有正确的 Node.js 版本(检查
.nvmrc文件) - 检查构建日志中的错误
- 确保设置了所有必需的环境变量
总结
Mapbox GL JS 构建系统是基于现代 JavaScript 工具的灵活且强大的系统。它能够为不同环境创建优化的包,并提供具有测试和代码生成功能的全面开发工作流。了解构建系统对于为库做出贡献或为特定用例创建自定义构建至关重要。