企业官网建设流程全解析

在使用 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

并伴随警告：

Couldn't 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/

⚙️ 五、关键配置（必须）

在地图初始化前设置：

importesriConfigfrom"geoscene/config";esriConfig.fontsUrl="/fonts";

🧩 六、TextSymbol 正确写法

importTextSymbolfrom"geoscene/symbols/TextSymbol";constsymbol=newTextSymbol({text:"朝阳区",color:"black",font:{family:"simsun-regular",size:12}});

📥 七、字体下载方案（关键步骤）

由于官方不提供完整打包下载，需要手动拉取 pbf 文件。

🚀 方法1：wget 批量下载

wget-r-np-nH--cut-dirs=3\https://doc.geoscene.cn/resources/fonts/simsun-regular/

🚀 方法2：Node 脚本下载（推荐）

通过脚本批量下载 Unicode 区间：Node 脚本下载参考步骤

• 自动下载 pbf
• 自动重试
• 支持断点恢复
• 可生成精简字体包

⚠️ 八、常见坑总结

❌ 坑1：只改 TextSymbol 不生效

👉 错误认知：

换 font.family = Arial 就能显示

✔ 实际：

必须字体 pbf 成功加载

❌ 坑2：assetsPath ≠ fontsUrl

esriConfig.assetsPath="/assets";❌ 不管字体 esriConfig.fontsUrl="/fonts";✔ 控制字体

❌ 坑3：缺少中文 Unicode 区间

必须包含：

19968–21247

否则中文会“部分消失”

🚀 九、优化方案（生产级建议）

✔ 推荐字体组合

✔ 推荐结构

/public/fonts/ simsun-regular/ arial-unicode-ms-regular/

✔ 推荐配置

esriConfig.fontsUrl="/fonts";

🎯 十、最终总结

Geoscene / ArcGIS 前端文字不显示的本质原因是：

❗字体不是系统字体，而是依赖 pbf glyph 文件加载

解决方案核心只有一句话：

✔ 将 fonts 资源本地化，并通过 fontsUrl 指向本地路径