错误与排查

两种错误通道

创建失败或参数/操作错误通过异常或 Promise rejection 返回；后台瓦片与渲染异常通过 error 事件上报。不要只写事件监听而忽略初始化的 catch。

import { createMap, MapSDKError } from '@shardx-map/sdk';

try {
  const map = await createMap(options);
  map.on('error', ({ code, message, recoverable }) => {
    showStatus(`${code}: ${message}`, recoverable);
  });
  await map.setSource(nextSource);
} catch (error) {
  if (error instanceof MapSDKError) console.warn(error.code, error.message);
  else console.warn('请由应用记录脱敏后的异常');
}

上例的 options、nextSource、showStatus 由业务提供。SDK 不提供自动重试、故障底图切换或统一错误 UI。

code	常见原因	处理方向
`CONFIG`	容器、坐标、颜色、source 字段、资源根路径不合法；修改了要素 id/type	修正参数；核对 API 类型
`INITIALIZATION`	WebGL、浏览器环境或 Viewer 初始化失败	检查浏览器、GPU、控制台与静态资源
`DUPLICATE_ID`	重复图层 ID 或同层重复要素 ID	更新已有对象或分配新 ID
`NOT_FOUND`	图层或要素尚未创建、已被删除	核对业务生命周期和操作顺序
`DESTROYED`	使用已销毁实例	停止相关异步业务，创建新实例
`TILE_LOAD`	key、权限、额度、网络、跨域或矩阵配置问题	检查网络响应与供应商配置；事件 recoverable 为 true 也不保证会自动恢复
`MODEL_LOAD`	3D Tiles 元数据或子内容加载失败（401、CORS、网络、格式等）	根加载拒绝 Promise 并释放 ID；子内容失败通过事件报告。核对认证与子资源地址
`RENDER`	场景渲染异常	事件标记 recoverable 为 false；保留脱敏诊断并按业务决定是否重建
`GEOFENCE_LOAD`	围栏 HTTP 请求、JSON 解析或多边形数据校验失败	检查地址、CORS、闭合环及经纬度；失败释放图层 ID，可修改后重试

事件中的 sourceId 来自 source.id，省略时为 source 类型。错误消息中的 HTTP(S) URL 与部分常见凭据字段会被脱敏，但这不保证业务 ID、第三方响应或浏览器控制台绝不含敏感信息。上传日志前仍需业务审核。

模型错误的 sourceId 是模型图层 ID。模型根加载失败同时拒绝 Promise 并发出事件；错误节流不代表重试。加载中删除模型会取消挂载，原 Promise 最终以 NOT_FOUND 拒绝；加载中销毁实例则以 DESTROYED 拒绝。底层网络请求可能仍完成，但已取消的模型不会重新插入场景。

常见症状

症状	优先检查
页面空白	容器是否有高度、是否连接到 DOM、是否 await createMap、是否导入 CSS
地球出现但底图空白	key 白名单、供应商 401/403/429、CORS、HTTPS 混合内容、服务覆盖范围
Worker 报错、Unexpected token `<`	`/cesium/` 请求是否被 SPA 回退成 HTML、资源是否完整且版本一致
瓦片错位	WMTS matrix set / labels / tilingScheme、输入坐标是否混入 GCJ-02/BD-09
DOM 标注不见	图层与要素 visible、地球背面隐藏、DOM 被另一个标注移走、业务元素尺寸与 CSS
npm 包读取 404	版本尚未发布、私有作用域路由错误；本模板的私有作用域不会回源公网
npm 发布 401/403	HTTPS 域名对应的登录状态、账户是否存在、作用域权限、token 是否过期
发布 413	Nginx 与 Verdaccio 两端 body 限制都为 20 MB；先检查包内是否误带资源

截图、HAR、错误堆栈中也可能包含天地图 key、token 与业务坐标。对外提交诊断前先脱敏。

错误与排查 ​

两种错误通道 ​

常见症状 ​

错误与排查

两种错误通道

常见症状