Mapbox GL JS 3.27.0：道路高程、中文竖排与非墨卡托投影修复

预计阅读时间：9 分钟

Mapbox GL JS 3.27.0 的改动同时触及构建工具、符号渲染、道路高程和非墨卡托投影。对普通二维地图来说，这可能只是一次小版本升级；但如果项目包含三维道路、栅格图层、中文竖排标注或复杂表达式，这几个变化值得安排有针对性的回归测试。

这次更新影响哪些场景

版本更新包含四类值得关注的变化：

项目升级到 TypeScript 7，主要影响参与源码构建、类型检查或扩展 Mapbox GL JS 的开发者。
symbols 增加 cross-source HD roads elevation 支持，重点改善跨数据源道路符号与高程数据协同工作的能力。
垂直文本渲染模式调整了部分中日韩字符的旋转逻辑，地图中的中文、日本语和韩语竖排标签可能因此发生视觉变化。
修复非墨卡托投影下的栅格数组越界断言，以及表达式读取对象属性字符串时的错误。

其中，后两项修复直接关系到运行稳定性。使用 globe 等非墨卡托投影时，栅格瓦片需要经过不同于传统 Web Mercator 的投影和采样过程；数组边界问题可能只在特定缩放级别、视角或瓦片边缘出现，因此不能只验证地图能否完成首次加载。

道路高程与符号渲染需要一起验证

道路高程并不只是把一条线抬高。真实项目往往会同时处理道路几何、名称符号、盾牌图标、桥梁层级和来自不同 source 的数据。新增的 cross-source HD roads elevation 能力针对的正是这种跨数据源组合场景。

升级后建议选择一段包含高架、匝道、桥梁或隧道的区域，检查以下内容：

道路和文字是否位于一致的视觉高度。
相机倾斜后，道路符号是否出现漂浮、穿透或跳动。
不同数据源在瓦片边界附近是否连续。
缩放跨越道路图层的 minzoom、maxzoom 时，符号是否突然错位。

摘要没有给出这一能力的具体公开 API，因此不应假设需要新增某个样式字段。更稳妥的做法是保持现有样式配置，升级运行时后用包含高程数据的生产样式进行对比测试。

可以这样实践：搭建一个投影与栅格回归页

下面的页面固定加载 Mapbox GL JS 3.27.0，并提供 Mercator、Globe 和 Equal Earth 三种投影切换。它还叠加一个栅格源，适合复测非墨卡托投影下的瓦片加载、旋转和缩放。

运行前，把 YOUR_MAPBOX_ACCESS_TOKEN 替换为自己的访问令牌，然后将内容保存为 index.html。由于浏览器和瓦片服务可能限制本地文件请求，建议通过本地 HTTP 服务打开：

python3 -m http.server 8080

访问 http://localhost:8080：

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mapbox GL JS 3.27.0 投影回归</title>
  <link href="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.css" rel="stylesheet">
  <script src="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.js"></script>
  <style>
    html, body, #map { width: 100%; height: 100%; margin: 0; }
    #projection {
      position: absolute;
      z-index: 1;
      top: 12px;
      left: 12px;
      padding: 8px;
      background: white;
    }
  </style>
</head>
<body>
  <select id="projection" aria-label="地图投影">
    <option value="mercator">Mercator</option>
    <option value="globe">Globe</option>
    <option value="equalEarth">Equal Earth</option>
  </select>
  <div id="map"></div>

  <script>
    mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

    const map = new mapboxgl.Map({
      container: 'map',
      style: 'mapbox://styles/mapbox/standard',
      center: [116.397, 39.908],
      zoom: 3,
      projection: 'mercator'
    });

    map.addControl(new mapboxgl.NavigationControl());

    map.on('load', () => {
      map.addSource('raster-regression', {
        type: 'raster',
        tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
        tileSize: 256,
        maxzoom: 19,
        attribution: '&copy; OpenStreetMap contributors'
      });

      map.addLayer({
        id: 'raster-regression',
        type: 'raster',
        source: 'raster-regression',
        paint: { 'raster-opacity': 0.35 }
      });
    });

    map.on('error', (event) => {
      console.error('Mapbox error:', event.error || event);
    });

    document.querySelector('#projection').addEventListener('change', (event) => {
      map.setProjection(event.target.value);
    });
  </script>
</body>
</html>

测试时不要只点击一次投影选项。可以在每种投影下连续缩放、旋转和拖动到日期变更线附近，并观察控制台是否出现断言、数组越界或瓦片加载异常。公共栅格服务适合本地验证，不应在高流量生产环境中无约束使用。

表达式与中日韩文本怎么回归

表达式修复需要覆盖真实样式中的对象属性访问。可以先扫描样式 JSON 里的 get、has、match 和 case，再挑选属性缺失、值为字符串以及嵌套对象等输入进行测试。例如，下面是一个可改造的嵌套属性读取表达式：

const colorExpression = [
  'match',
  ['get', 'level', ['get', 'meta']],
  'critical', '#c62828',
  'warning', '#f9a825',
  '#2e7d32'
];

这里假设要素的 meta 属性是对象，且包含字符串属性 level。应把字段名和值替换成项目中的真实数据结构，并验证属性缺失时的回退颜色。该示例用于构造回归用例，并不意味着 3.27.0 的缺陷只发生在这一种表达式结构中。

中日韩竖排文本则更适合视觉回归。应准备包含中文标点、括号、全角字符、拉丁字母和数字的地名样本，在升级前后使用相同中心点、缩放级别和字体生成截图。旋转逻辑的改善可能让截图产生预期差异，不能简单地把所有像素变化都判定为回归。

升级前的检查清单

建议先在预发布环境固定到 mapbox-gl@3.27.0，避免版本范围在构建时继续漂移：

npm install --save-exact mapbox-gl@3.27.0
npm ls mapbox-gl

随后完成以下检查：

对比 Mercator 与项目使用的全部非墨卡托投影。
覆盖 raster、raster-array 以及自定义栅格数据源。
检查跨 source 的道路、符号和高程效果。
为中文、日文、韩文竖排标签保留升级前后截图。
用缺失属性、字符串属性和嵌套对象执行样式表达式测试。
记录浏览器控制台错误，并在移动设备或低端 GPU 上复测交互。

这次升级的风险主要集中在渲染边界条件，而不是常规地图初始化。已有自动化截图和固定测试地点的团队可以较快采用；依赖复杂三维道路或自定义栅格管线的项目，则应先建立可重复的场景，再推进生产发布。