TypeScript搭建Mapbox自定义3D模型图层不显示问题排查

尝试用TypeScript复现Mapbox官方的添加3D模型示例，但预期的GLTF模型并未出现在指定坐标处。以下是针对代码的问题排查与修复方案：

核心问题与修复 #

1. 坐标系平移参数顺序颠倒 #

在render方法的矩阵变换中，makeTranslation的参数顺序错误，导致模型位置完全偏离目标坐标。Mapbox的Mercator坐标中，translateX对应x轴、translateY对应y轴，但代码中把两者互换了。

修复代码：

const l = new THREE.Matrix4()
  // 修正平移参数顺序
  .makeTranslation(
    this.modelTransform.translateX,
    this.modelTransform.translateY,
    this.modelTransform.translateZ ?? 0
  )
  // 调整矩阵变换顺序：先旋转，再缩放，避免基点偏移
  .multiply(rotationX)
  .multiply(rotationY)
  .multiply(rotationZ)
  .scale(
    new THREE.Vector3(
      this.modelTransform.scale,
      -this.modelTransform.scale,
      this.modelTransform.scale
    )
  );

2. 模型文件路径问题 #

代码中加载./mydata.gltf，需确保文件位于项目静态资源目录，且能被浏览器正确访问：

• 检查浏览器控制台网络请求，确认模型文件无404错误
• 若本地文件存在问题，可先替换为测试模型验证逻辑

3. 无效图层操作引发报错 #

代码中执行map.setLayoutProperty("highlight", "visibility", "visible")，但当前地图样式中不存在highlight图层，会抛出错误中断渲染逻辑，需删除该行代码。

4. 箭头函数语法错误 #

查找标签图层ID的代码存在语法错误，导致图层添加失败：
错误代码：

const labelLayerId = layers.find(
  (layer) =
    layer.type === "symbol" &&
    layer.layout !== undefined &&
    layer.layout["text-field"]
)?.id;

修复后：

const labelLayerId = layers.find(
  (layer) =>
    layer.type === "symbol" &&
    layer.layout !== undefined &&
    layer.layout["text-field"]
)?.id;

5. 异步加载时机控制 #

Mapbox的CustomLayer onAdd方法默认不支持异步Promise，可能导致模型未加载完成就开始渲染。可添加加载状态判断：

// 在CustomIFCLayer类中新增属性
private modelLoaded = false;

// 在onAdd方法加载完成后标记状态
const gltf = await loader.loadAsync("./mydata.gltf");
this.scene.add(gltf.scene);
this.modelLoaded = true;

// 在render方法中先判断加载状态
render(gl: WebGL2RenderingContext, matrix: Array<number>) {
  if (!this.modelLoaded) return;
  // 后续渲染逻辑...
}

测试建议 #

1. 打开浏览器控制台，排查是否存在JavaScript语法错误或资源加载失败
2. 调整地图zoom和pitch参数，确保模型在当前视图范围内
3. 先使用官方示例模型验证逻辑，排除本地文件路径问题

内容的提问来源于stack exchange，提问作者MiguelG