开发工具和资源

本页提供了适用于使用 Mapbox GL JS 代码库的开发人员的工具、实用程序和资源的全面概述。无论您是从源代码构建库、调试渲染问题还是扩展功能,本指南都将帮助您导航开发生态系统。

有关特定主题的更详细信息,请参阅以下子页面:

构建系统 - 从源代码构建 Mapbox GL JS 的详细说明
测试和调试 - 测试框架和调试工具的全面指南
网络和 AJAX - 请求处理和转换的深入介绍

开发环境设置

要有效地使用 Mapbox GL JS 代码库,您需要设置一个开发环境:

克隆仓库:git clone https://github.com/mapbox/mapbox-gl-js.git
安装依赖:npm ci
运行开发服务器:npm start

开发服务器将监视源文件的更改并自动重建库。

构建系统概述

Mapbox GL JS 使用以 Rollup 为中心的现代构建系统,配备了用于 TypeScript 转译、模块解析和代码压缩的插件。构建过程会创建针对不同用例优化的多个产物。

构建系统架构

100%

关键构建命令

该仓库为不同的构建场景提供了各种 npm 脚本:

Command	Description
`npm run build-dev`	带有 source maps 和调试工具的开发构建
`npm run watch-dev`	开发监视模式
`npm run build-prod`	生产构建(未压缩)
`npm run build-prod-min`	压缩后的生产构建
`npm run build-csp`	符合内容安全策略的构建
`npm run build-css`	构建 CSS 样式表
`npm run build-style-spec`	构建样式规范模块
`npm run build-dts`	生成 TypeScript 声明文件

开发工作流

对于主动开发,该仓库提供了一个便捷的启动脚本:

npm start

此命令并行运行多个进程:

生成 access token 脚本
监视 CSS 文件的更改
监视源文件并在开发模式下重建
在端口 9966 上启动静态 HTTP 服务器

测试基础设施

Mapbox GL JS 实现了全面的测试方法,包含多种测试类型和运行器。这既确保了单元级别的正确性,又确保了在浏览器之间的正确视觉渲染。

测试架构

100%

关键测试类型

该代码库包含几种类型的测试:

单元测试: 使用 Vitest 测试单个组件
- 运行 npm run test-unit
渲染测试: 渲染功能的视觉回归测试
- 每个测试都有一个样式规范和预期输出图像
- 示例:test/integration/render-tests/debug/collision-pitched/style.json
- 运行 npm run test-render
查询测试: 空间查询功能的测试
- 运行 npm run test-query
表达式测试: 样式表达式评估系统的测试
- 运行 npm run test-expressions
类型检查: TypeScript 类型的验证
- 运行 npm run test-typings

持续集成

CI/CD 由 CircleCI 处理,它在多个平台(Linux、macOS、Windows)和浏览器(Chrome、Firefox、Safari)上运行测试。配置定义在 .circleci/config.yml 中

调试工具

Mapbox GL JS 包括几个内置调试工具,以帮助诊断渲染问题和性能问题。

调试 UI

使用开发构建时,您可以通过设置 devtools 选项启用调试 UI:

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    devtools: true
});

此 UI 提供用于检查地图属性、监视性能指标和可视化内部状态的控件。

调试渲染模式

几种调试渲染模式有助于可视化内部渲染结构:

碰撞框: 可视化文本和图标的碰撞检测
- 使用 map.showCollisionBoxes = true 启用
- 在 src/shaders/collision_box.vertex.glsl 和 src/shaders/collision_box.fragment.glsl 中实现
- 示例测试用例:test/integration/render-tests/debug/collision-pitched/style.json
瓦片边界: 可视化瓦片加载和边界
- 使用 map.showTileBoundaries = true 启用
地形线框: 可视化地形网格(当地形启用时)
- 使用 map.showTerrainWireframe = true 启用

性能监视

要监视性能,请使用 renderstart 和 render 事件来测量帧渲染持续时间:

map.on('renderstart', () => { /* 记录开始时间 */ });
map.on('render', () => { /* 计算帧持续时间 */ });

网络请求架构

Mapbox GL JS 实现了一个灵活的系统来处理网络请求,支持请求转换、身份验证和缓存。

请求管道

网络系统通过以下管道处理请求:

请求创建: 为资源(样式、瓦片等)生成请求
请求转换: 应用自定义转换(如果配置)
身份验证: 添加 access token 和凭据
请求执行: 发送 HTTP 请求
响应缓存: 缓存响应以提高性能
响应解析: 将响应解析为适当的格式

自定义请求

您可以通过提供 transformRequest 函数来自定义网络请求:

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    transformRequest: (url, resourceType) => {
        // 修改请求
        return { url, headers, credentials, method };
    }
});

resourceType 参数标识资源类型:

'Style': Style JSON 文档
'Source': Source 数据
'Tile': 地图瓦片
'Glyphs': 字体字形
'SpriteImage': Sprite 图像
'SpriteJSON': Sprite 元数据
'Image': 自定义图像

开发资源

代码组织

Mapbox GL JS 代码库组织为几个主要目录:

src/: 源代码
- src/style-spec/: 样式规范实现
- src/render/: 渲染引擎
- src/geo/: 地理实用程序
- src/ui/: UI 组件(markers、popups、controls)
- src/util/: 实用程序函数
- src/shaders/: GLSL shader 代码
test/: 测试代码
- test/unit/: 单元测试
- test/integration/: 集成测试(渲染、查询)
- test/build/: 构建测试
debug/: 调试实用程序和示例
dist/: 构建输出(在构建期间生成)

开发工具

该仓库包括几个有助于维护代码质量的工具:

Linting:
- 用于 JavaScript/TypeScript 的 ESLint:npm run lint
- 用于 CSS 的 Stylelint:npm run lint-css
- 配置在 .stylelintrc 中
包大小检查:
- 确保包大小不超过限制
- 运行 npm run check-bundle-size
TypeScript 抑制检查:
- 监视 TypeScript 错误抑制
- 运行 npm run check-ts-suppressions
代码生成:
- 为样式规范、结构数组等生成代码
- 运行 npm run codegen

社区资源

除了代码仓库本身之外,这些资源可以帮助使用 Mapbox GL JS 的开发人员:

API 文档:https://docs.mapbox.com/mapbox-gl-js/api/
样式规范:https://docs.mapbox.com/mapbox-gl-js/style-spec/
示例画廊:https://docs.mapbox.com/mapbox-gl-js/examples/
GitHub 仓库:https://github.com/mapbox/mapbox-gl-js
贡献指南:CONTRIBUTING.md

依赖管理

Mapbox GL JS 使用 npm 进行依赖管理。核心依赖项列在 package.json18-46 中,开发依赖项列在 package.json48-122 中

关键依赖项包括:

@mapbox/vector-tile: 矢量瓦片解码
geojson-vt: GeoJSON 矢量瓦片处理
earcut: WebGL 渲染的 Polygon 三角剖分
gl-matrix: WebGL 的矩阵数学运算
supercluster: 点聚类算法

TypeScript 类型定义也作为依赖项包括在内,以确保类型安全。

使用样式规范工具

Mapbox GL 样式规范作为一个单独的 npm 包(@mapbox/mapbox-gl-style-spec)发布,其中包括几个命令行实用程序:

Tool	Description
`gl-style-validate`	根据规范验证样式
`gl-style-format`	格式化样式以使其更具可读性
`gl-style-migrate`	将样式从旧版本迁移
`gl-style-composite`	将多个样式组合在一起

这些工具在 src/style-spec/package.json39-44 中定义,可以通过 npm 安装或直接从仓库中使用。

开发工具和资源 ​

开发环境设置 ​

构建系统概述 ​

构建系统架构 ​

关键构建命令 ​

开发工作流 ​

测试基础设施 ​

测试架构 ​

关键测试类型 ​

持续集成 ​

调试工具 ​

调试 UI ​

调试渲染模式 ​

性能监视 ​

网络请求架构 ​

请求管道 ​

自定义请求 ​

开发资源 ​

代码组织 ​

开发工具 ​

社区资源 ​

依赖管理 ​

使用样式规范工具 ​