标注字体没加载，glyphs 404 导致文字全不显示

现象

symbol 图层的 text-field 设置正确，数据里也有名称， 但地图上没有任何文字。网络面板里可见：

GET /fonts/Microsoft%20YaHei%20Regular/0-255.pbf   404 Not Found
GET /fonts/Microsoft%20YaHei%20Regular/256-511.pbf  404 Not Found

控制台报 Error: Failed to load glyphs: 404， 但不会中断地图加载，只是文字全部缺失。

原因

Mapbox GL 的文字不是用系统字体渲染的，而是预先切成 SDF（有向距离场）的 PBF 切片， 按 Unicode 区段分批加载。glyphs 配置的地址模板是 {fontstack}/{range}.pbf。

• 字体名必须与服务端 fonts/ 目录下的文件夹名完全一致，含空格与大小写。
• 中文字符落在 256-511、19968-20223 等多个区段，缺一段就缺一批字。
• 自建服务时常常只拷贝了 0-255 切片，中文字一个都没有。

排查过程

1. 网络面板筛选 pbf，看哪些区段 404。
2. 把其中一个 URL 直接在地址栏打开，确认服务端是否有该文件。
3. 检查 glyphs 模板里的字体栈，与服务器目录名逐字比对。
4. 确认切片目录是否包含中文字段，缺的话需要重新生成。

// 样式里的字体栈
"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf",
"layers": [{
  "id": "label",
  "type": "symbol",
  "layout": {
    "text-field": ["get", "name"],
    "text-font": ["Microsoft YaHei Regular"]   // 必须与目录名一致
  }
}]

解决方案

用自己生成好中文字段的字体，或改用 MapLibre 的本地字体方案。 字体栈可以给多个候选，引擎会按顺序回退。

// 方式一：自建 glyphs，用 fonts 目录
// fonts/Noto Sans SC Regular/0-255.pbf ... 19968-20223.pbf

"text-font": ["Noto Sans SC Regular"]

// 方式二：字体栈回退，中文缺失时用英文兜底
"text-font": ["Noto Sans SC Regular", "Open Sans Regular"]

// 方式三：MapLibre 可用 localIdeographFontFamily 直接调系统字体渲染中文
const map = new maplibregl.Map({
  container: 'map',
  style: style,
  localIdeographFontFamily: "'Microsoft YaHei', 'PingFang SC', sans-serif"
});

localIdeographFontFamily 只对 CJK 字符生效， 拉丁字符仍走 glyphs 切片，因此两条路要同时配好。

验证

网络面板中 pbf 请求全部 200； 地图上中文标注正常显示；queryRenderedFeatures 返回带 name 属性的要素。

const r = map.queryRenderedFeatures({ layers: ['label'] });
console.assert(r.length > 0, '文字仍未渲染');
const failed = performance.getEntriesByType('resource')
  .filter(e => e.name.endsWith('.pbf') && e.transferSize === 0);
console.assert(failed.length === 0, '仍有 glyphs 404：' + failed.length);

适用版本