MapBox SDK样式解析失败：自定义OpenMapTiles服务适配问题排查

这个Failed to parse style: 0 - Invalid value报错说明MapBox SDK没法正确解析你传入的样式JSON，结合你用OpenMapTiles自建服务器的场景，大概率是格式不兼容或者网络访问限制导致的，下面是具体的排查和解决步骤：

1. 别混淆TileJSON和MapBox Style规范 #

你提到用的是TileJSON 2.0的Dark Matter样式，但MapBox SDK的setStyleJson方法只认符合MapBox Style Specification的JSON——这俩是完全不同的格式：

• TileJSON只是用来描述瓦片集的元数据（比如瓦片地址、坐标系、覆盖范围），没有视觉样式定义；
• MapBox Style JSON是完整的地图样式配置，包含数据源、图层样式、字体等所有视觉相关的内容，版本要求是v8。

解决办法： #

你需要替换成符合MapBox Style v8规范的Dark Matter样式文件。OpenMapTiles官方提供的Dark Matter样式就是兼容MapBox的，标准的样式JSON结构应该长这样：

{
  "version": 8,
  "name": "Dark Matter",
  "sources": {
    "openmaptiles": {
      "type": "vector",
      "url": "http://192.168.1.65:8080/data/v3.json" // 这里指向你的TileJSON数据源
    }
  },
  "layers": [
    // 这里是各种图层的样式定义，比如背景色、道路样式、建筑填充等
  ]
}

如果你的dark-matter.json是TileJSON格式（比如version字段是2），那肯定会解析失败，直接替换成MapBox兼容的版本就行。

2. 检查Android的明文HTTP访问限制 #

从Android 9（API 28）开始，系统默认禁止应用访问明文HTTP资源，你的样式地址是http://192.168.1.65:8080/...，属于明文HTTP，很可能被系统拦截，导致SDK根本拿不到JSON内容，自然解析失败。

解决办法： #

• 先在AndroidManifest.xml的<application>标签中添加明文访问许可：

<application
    ...
    android:usesCleartextTraffic="true">
    <!-- 其他配置 -->
</application>

• 如果你的项目targetSdk是30及以上，还需要配置网络安全规则：
  1. 在res/xml目录下创建network_security_config.xml，内容如下：

  <?xml version="1.0" encoding="utf-8"?>
  <network-security-config>
      <domain-config cleartextTrafficPermitted="true">
          <domain includeSubdomains="true">192.168.1.65</domain>
      </domain-config>
  </network-security-config>
  

  2. 在AndroidManifest.xml的<application>标签中引用这个配置：

  <application
      ...
      android:networkSecurityConfig="@xml/network_security_config">
  </application>
  

3. 验证样式JSON和数据源的可达性 #

先确认设备能正常访问你的服务器资源：

• 用设备自带的浏览器打开http://192.168.1.65:8080/styles/dark-matter.json，看能不能正常加载到完整的JSON内容；
• 检查样式JSON里sources字段中的数据源URL，在浏览器中打开，确认是有效的TileJSON或者瓦片服务；
• 确保你的设备和地图服务器在同一个局域网内，IP地址没有写错（比如把192.168.1.65写成了192.168.1.66）。

4. 确认样式JSON的版本号 #

MapBox Style Specification的最低兼容版本是8，如果你的样式JSON的version字段不是8，SDK会直接解析失败。打开你的dark-matter.json检查一下，要是version是2（TileJSON的版本），那肯定不符合要求，替换成正确的样式文件即可。

内容的提问来源于stack exchange，提问作者Sergio Sánchez