MapLibre GL JS加载本地mbtiles、glyphs和sprites问题求助

一、Sprite加载错误解决 #

你遇到的Unable to parse URL "./sprites/sprite"错误，核心原因及解决方法：

• 文件完整性问题：MapLibre GL JS要求sprite配置的路径是基础文件名，必须同时存在sprite.json（精灵图元数据）和sprite.png（精灵图图片）两个文件在指定目录下。比如配置"sprite": "./sprites/sprite"，则./sprites/目录里必须有这两个文件。
• 本地跨域限制：直接用file://协议打开HTML文件时，浏览器会限制本地资源加载，导致无法读取sprite。解决方法是启动本地HTTP服务器，比如用Python命令：

  python -m http.server 8000
  

  之后通过http://localhost:8000访问页面，再验证http://localhost:8000/sprites/sprite.json是否能正常返回JSON内容。

二、MBTiles加载错误解决 #

Error: Unexpected token 'S', "SQLite for"... is not valid JSON错误是因为MapLibre/Mapbox GL JS不支持直接加载MBTiles文件——MBTiles是SQLite数据库格式，无法被前端直接解析。纯网页离线方案有两种可行路径：

方案1：将MBTiles转成静态瓦片目录 #

用工具把MBTiles内的瓦片导出为z/x/y结构的静态文件，比如用mapbox-tile-copy：

mapbox-tile-copy ./mbtiles/country.mbtiles ./tiles/{z}/{x}/{y}.png

之后在style.json中配置静态瓦片源：

{
  "sources": {
    "country": {
      "type": "raster", // 矢量MBTiles则改为"vector"
      "tiles": ["./tiles/{z}/{x}/{y}.png"],
      "tileSize": 256
    }
  }
}

方案2：本地启动瓦片服务加载MBTiles #

如果不想导出静态瓦片，可使用tileserver-gl启动本地瓦片服务：

npm install -g tileserver-gl
tileserver-gl ./mbtiles/country.mbtiles

再在style.json中配置服务地址：

{
  "sources": {
    "country": {
      "type": "vector", // 或raster，匹配MBTiles类型
      "tiles": ["http://localhost:8080/styles/bright/{z}/{x}/{y}.pbf"]
    }
  }
}

三、离线支持说明 #

• MapLibre GL JS完全支持纯网页离线方案，只要所有资源（静态瓦片、sprite、glyphs）能通过HTTP访问（本地服务器或打包后的静态资源）即可。
• Mapbox GL JS的离线逻辑和MapLibre一致，纯离线场景下两者配置通用，仅部分Mapbox专有服务功能存在差异。

额外注意事项 #

• 所有离线资源的路径需对应本地服务器的相对路径或绝对URL。
• 确保资源格式符合要求：矢量瓦片为PBF格式，sprite必须包含对应的json和png文件，glyphs需按字体栈、范围划分成PBF文件。

内容的提问来源于stack exchange，提问作者Ben On Track