Mapbox GL JS 中关于批量模型源相对路径问题的技术解析

背景介绍

Mapbox GL JS 是一个强大的Web地图渲染库，它支持3D模型的批量加载功能。在实际开发中，开发者经常需要指定模型资源的位置路径。最近有开发者反馈，在使用批量模型源(batched-model)时，相对路径在tiles属性中无法正常工作。

问题现象

当开发者尝试在batched-model类型的源中使用相对路径时，例如：

map.addSource('bag-3d', {
  "type": "batched-model",
  "tiles": [
    "./content/{z}-{x}-{y}.glb"
  ]
});

发现模型资源无法正常加载。而改为使用绝对路径后，问题得到解决：

map.addSource('bag-3d', {
  "type": "batched-model",
  "tiles": [
    "https://example.com/content/{z}-{x}-{y}.glb"
  ]
});

技术原理

这个现象并非bug，而是由TileJSON规范的设计决策导致的。batched-model源中的tiles属性遵循TileJSON 3.0.0规范，该规范明确要求所有URL必须是绝对路径。

规范做出这一要求主要基于以下技术考虑：

1. 路径解析歧义：相对路径的解析基准不明确。它可能是相对于TileJSON文件的URL，也可能是相对于样式文件的URL，或者是当前页面的URL。当TileJSON直接内联在样式中时，情况会更加复杂。

2. 一致性保证：绝对URL能确保资源位置在不同环境下保持一致，避免因部署路径变化导致的资源加载失败。

3. 缓存机制：使用绝对路径有利于浏览器和CDN实施更有效的缓存策略。

最佳实践建议

对于需要在不同环境中部署的项目，开发者可以采用以下方法：

1. 构建时路径处理：在项目构建阶段，通过构建工具(如Webpack、Vite等)将资源路径转换为部署环境的绝对路径。

2. 环境变量配置：使用环境变量来动态生成资源的基础URL，例如：

const baseUrl = process.env.ASSET_BASE_URL || 'https://example.com';
map.addSource('bag-3d', {
  "type": "batched-model",
  "tiles": [
    `${baseUrl}/content/{z}-{x}-{y}.glb`
  ]
});

3. 服务端动态生成：如果资源路径需要根据请求动态确定，可以在服务端生成包含正确绝对路径的TileJSON响应。

总结

Mapbox GL JS对batched-model源中tiles路径的要求是基于TileJSON规范的设计决策，旨在确保资源定位的一致性和可靠性。开发者应当理解这一设计背后的技术考量，并在项目中采用适当的策略来处理资源路径问题，以确保3D模型资源能够正确加载和显示。