MapboxGL Wiki

简体中文

English

简体中文

English

Appearance

测试和调试 ​

本文档提供了 Mapbox GL JS 中可用的测试框架和调试工具的全面概述。它涵盖了如何运行测试、设置调试环境以及有效地排查库中的问题。

测试框架概述 ​

Mapbox GL JS 采用强大的测试基础设施,以确保在不同环境和用例中的可靠性。测试框架由在多个平台和浏览器上运行的几种测试类型组成。

SVG
100%

单元测试 ​

单元测试验证单个组件在隔离状态下的功能。这些测试专注于 JavaScript 逻辑,并且与浏览器无关。

集成测试 ​

集成测试套件包括几种测试类型:

渲染测试 ​

渲染测试将渲染的地图输出与预期图像进行比较,以检测视觉回归。这些测试在不同的浏览器和平台上运行。

SVG
100%

查询测试 ​

查询测试验证地图查询函数(如 queryRenderedFeatures())的行为,确保在查询地图时返回正确的 features。

其他测试类型 ​

  • 表达式测试: 验证 Mapbox GL JS 表达式的操作
  • 样式规范测试: 检查是否符合 Mapbox GL 样式规范
  • TypeScript 测试: 验证 TypeScript 类型定义
  • CSP 测试: 确保内容安全策略合规性
  • uSVG 测试: 测试 SVG 渲染

CI/CD 管道 ​

Mapbox GL JS 使用 CircleCI 进行持续集成。配置为各种平台和浏览器上的不同测试类型定义了作业。

SVG
100%

调试工具 ​

Mapbox GL JS 提供了几个调试工具和选项,以帮助识别和修复问题。

地图调试选项 ​

创建地图时可以启用 devtools 选项以提供额外的调试信息:

var map = new mapboxgl.Map({
    container: 'map',
    devtools: true,
    // other options...
});

碰撞框调试 ​

可以通过启用 collisionDebug 选项来可视化文本和图标的碰撞框。这有助于通过显示以下内容来调试符号放置问题:

  • 碰撞标签(隐藏)的红色框
  • 可见标签的蓝色框
SVG
100%

调试页面 ​

该仓库在 debug/ 目录中包括几个用于特定调试场景的 HTML 页面:

地形调试 ​

地形调试页面允许切换各种与地形相关的功能:

  • 地形高度
  • 地球投影
  • 卫星图像
  • 建筑物
  • Hillshade
  • 自定义层

其他调试页面 ​

  • Padding 调试: 测试地图 padding 功能
  • RTL 调试: 测试从右到左的文本渲染
  • Canvas 大小调试: 测试 canvas 大小问题

本地运行测试 ​

要在本地运行测试,您可以使用以下 npm 脚本:

# 运行单元测试
npm run test-unit

# 使用 Chrome 运行渲染测试
npm run test-render

# 使用 Firefox 运行渲染测试
npm run test-render-firefox

# 运行查询测试
npm run test-query

# 运行表达式测试
npm run test-expressions

# 运行样式规范测试
npm run test-style-spec

测试目录结构 ​

SVG
100%

高级调试技术 ​

WebGL 调试 ​

由于 Mapbox GL JS 使用 WebGL 进行渲染,因此浏览器 WebGL 调试工具至关重要:

  1. Chrome WebGL Inspector: 在开发者工具 > 设置 > 实验 > WebGL 开发者工具中启用
  2. Firefox WebGL Debugger: 可在开发者工具 > 设置 > 可用工具 > WebGL Shader Editor 中获得

性能分析 ​

可以使用以下方法调试性能问题:

  1. 浏览器性能工具: 使用浏览器开发者工具中的性能选项卡
  2. 帧率计数器: 使用 map.showTileBoundaries = true; 启用
  3. 瓦片边界: 使用 map.showTileBoundaries = true; 启用

常见调试场景 ​

文本放置和碰撞问题 ​

要调试符号放置和碰撞问题:

  1. 启用碰撞调试以可视化碰撞框
  2. 检查 text-pitch-alignment 和 text-rotation-alignment 设置
  3. 检查 symbol-placement 和文本字段配置

地形和 3D 问题 ​

要调试地形和 3D 渲染:

  1. 使用地形调试页面来隔离与地形相关的问题
  2. 检查高度数据源和地形配置
  3. 检查 fill-extrusion 层是否存在建筑物问题

贡献新测试 ​

添加新功能或修复错误时,添加测试很重要:

  1. 针对新函数和方法的单元测试
  2. 针对视觉更改的渲染测试
  3. 针对查询行为更改的查询测试

典型的渲染测试包括:

  1. 定义地图样式和测试参数的 style.json 文件
  2. 显示预期渲染输出的 expected.png 文件

查询测试需要:

  1. 带有测试配置的 style.json 文件
  2. 带有预期查询结果的 expected.json 文件

结论 ​

Mapbox GL JS 提供全面的测试和调试工具,以确保可靠性并帮助排查问题。通过了解这些工具和技术,您可以有效地识别和修复 Mapbox GL JS 应用程序中的问题。

Copyright © 2026 LZUGIS