Geoscene / ArcGIS 前端文字标注不显示问题排查与本地字体方案

在使用 Geoscene或 ArcGIS JS API 体系进行地图开发时经常会遇到一个典型问题❗点位可以正常渲染但文字标注TextSymbol无法显示本文结合实际开发中的踩坑经历总结问题原因及最终通过本地字体pbf托管解决方案彻底修复该问题的方法。 一、问题现象在地图中使用TextSymbol或 labeling 时出现以下情况✔ 点Graphic正常显示❌ 文本标注不显示❌ 控制台出现字体加载失败控制台报错如下GET https://doc.geoscene.cn/resources/fonts/arial-unicode-ms-regular/xxxxx.pbf net::ERR_NAME_NOT_RESOLVED并伴随警告Couldnt find font simsun-regular. Falling back to Arial Unicode MS Regular 二、问题本质原因Geoscene / ArcGIS 的文字渲染机制并不是使用浏览器字体而是❗基于 WebGL glyph.pbf字体切片渲染也就是说 文字渲染流程TextSymbol → glyph请求pbf → 字体服务器 → WebGL渲染 核心问题点❌ 1. 默认字体依赖远程服务器默认字体资源来自https://doc.geoscene.cn/resources/fonts/如果网络不可访问DNS失败 / 内网环境 / 被墙就会导致字体无法加载文本无法渲染❌ 2. 字体不是系统字体即使写font:{family:Arial}也不会使用系统字体而是 仍然会去请求对应的 pbf 字体资源❌ 3. 缺少 glyph 区间中文字符依赖 Unicode 分片例如19968-20223.pbf 20224-20479.pbf缺失任意区间都会导致❌ 部分汉字直接不显示无报错 三、解决方案本地字体托管核心方案 思路将字体资源从远程迁移到本地项目中doc.geoscene.cn → 本地 /public/fonts 四、本地字体目录结构推荐结构如下public/ fonts/ arial-unicode-ms-regular/0-255.pbf256-511.pbf...19968-20223.pbf或中文优化版本public/fonts/simsun-regular/⚙️ 五、关键配置必须在地图初始化前设置importesriConfigfromgeoscene/config;esriConfig.fontsUrl/fonts; 六、TextSymbol 正确写法importTextSymbolfromgeoscene/symbols/TextSymbol;constsymbolnewTextSymbol({text:朝阳区,color:black,font:{family:simsun-regular,size:12}}); 七、字体下载方案关键步骤由于官方不提供完整打包下载需要手动拉取 pbf 文件。 方法1wget 批量下载wget-r-np-nH--cut-dirs3\https://doc.geoscene.cn/resources/fonts/simsun-regular/ 方法2Node 脚本下载推荐通过脚本批量下载 Unicode 区间Node 脚本下载参考步骤自动下载 pbf自动重试支持断点恢复可生成精简字体包⚠️ 八、常见坑总结❌ 坑1只改 TextSymbol 不生效 错误认知换 font.family Arial 就能显示✔ 实际必须字体 pbf 成功加载❌ 坑2assetsPath ≠ fontsUrlesriConfig.assetsPath/assets;❌ 不管字体 esriConfig.fontsUrl/fonts;✔ 控制字体❌ 坑3缺少中文 Unicode 区间必须包含19968–21247否则中文会“部分消失” 九、优化方案生产级建议✔ 推荐字体组合字体作用simsun-regular中文主字体arial-unicode-ms英文/兜底✔ 推荐结构/public/fonts/ simsun-regular/ arial-unicode-ms-regular/✔ 推荐配置esriConfig.fontsUrl/fonts; 十、最终总结Geoscene / ArcGIS 前端文字不显示的本质原因是❗字体不是系统字体而是依赖 pbf glyph 文件加载解决方案核心只有一句话✔ 将 fonts 资源本地化并通过 fontsUrl 指向本地路径