解决VS Code中TypeScript的mapbox-gl 'string'无法赋值给'Projection'错误

报错原因 #

mapbox-gl@2.15.0的TypeScript类型定义存在滞后性：

• 构造Map实例时的projection参数对应的Projection类型，仅包含部分早期支持的投影字面量，'naturalEarth'未被纳入该类型的允许范围；即便默认值'mercator'是字符串，类型定义也未正确兼容这种字符串字面量写法
• setProjection方法的类型定义已同步更新，包含了'globe'等更多投影类型，因此调用时不会触发类型报错
• 代码实际运行正常是因为JavaScript本身不做静态类型检查，mapbox-gl运行时逻辑完全支持'naturalEarth'投影，仅TypeScript的静态检查触发了误报

解决方法 #

1. 类型断言（快速修复） #

直接将字符串断言为Projection类型，绕过TypeScript静态检查：

map = new mapboxgl.Map({
  container: 'mapbox',
  style: 'mapbox://styles/mapbox/outdoors-v12',
  projection: 'naturalEarth' as mapboxgl.Projection
})

2. 扩展类型定义（规范方案） #

若需长期使用该投影且不想重复断言，可在项目中扩展Projection类型：
创建types/mapbox-gl.d.ts文件，添加以下内容：

declare module 'mapbox-gl' {
  type Projection = 'mercator' | 'naturalEarth' | 'globe';
}

确保tsconfig.json包含该类型文件路径，让TypeScript识别扩展后的类型。

3. 升级mapbox-gl版本 #

后续版本的mapbox-gl已修复此类型定义问题，升级到v2.18+等稳定版本后，类型定义会与运行时支持的投影类型保持一致，无需额外处理。

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