Android端模拟gzip编码传递.pbf文件至Mapbox GL JS遇阻

我之前在做Mapbox本地瓦片加载时也碰到过类似的坑，结合Mapbox GL Android的特性，给你梳理几个大概率的原因和对应的解决办法：

1. 本地PBF文件未实际做gzip压缩 #

Mapbox GL在收到Content-Encoding: gzip头时，会自动尝试解压响应内容。如果你的本地.pbf文件本身没有经过gzip压缩，解压步骤就会失败，直接导致请求被拒绝。

• 验证与解决：
  • 先确认文件是否是有效的gzip压缩文件：可以用终端执行gzip -t your_tile.pbf，没有报错说明是合法的压缩文件。
  • 如果未压缩，先对文件执行压缩：gzip your_tile.pbf，压缩后文件名会变成.pbf.gz，你可以重命名回.pbf（保持后缀和Mapbox的瓦片请求路径一致），或者在加载时调整文件名匹配规则。

2. 响应头配置不完整或格式错误 #

仅加Content-Encoding: gzip是不够的，Mapbox需要明确的文件类型标识，同时头的格式也得符合标准。

• 常见错误点：

  • 缺失Content-Type: application/x-protobuf头：Mapbox依赖这个头识别瓦片格式，和编码头必须同时设置。
  • 头的大小写不规范：虽然HTTP头不区分大小写，但部分Android网络库对标准写法更友好，建议严格写成Content-Encoding: gzip。

• 示例代码（以OkHttp本地服务为例）：

Interceptor tileInterceptor = chain -> {
    Request request = chain.request();
    String tilePath = request.url().path();
    
    if (tilePath.endsWith(".pbf")) {
        File localTile = new File(getFilesDir(), tilePath.substring(1));
        if (localTile.exists()) {
            return new Response.Builder()
                    .request(request)
                    .protocol(Protocol.HTTP_1_1)
                    .code(200)
                    .header("Content-Type", "application/x-protobuf")
                    .header("Content-Encoding", "gzip")
                    .body(ResponseBody.create(
                            new FileInputStream(localTile),
                            MediaType.parse("application/x-protobuf")
                    ))
                    .build();
        }
    }
    return chain.proceed(request);
};

3. Mapbox GL Android的瓦片数据源配置需同步指定编码 #

有时候仅靠响应头不够，需要在瓦片数据源的配置中明确指定压缩格式，让Mapbox提前知晓解压规则。

• 解决示例：

// 定义本地瓦片集时直接指定编码
TileSet localTileSet = new TileSet("local-tiles", "file:///android_asset/tiles/{z}/{x}/{y}.pbf");
localTileSet.setContentType("application/x-protobuf");
localTileSet.setContentEncoding("gzip");

// 添加到地图样式中
Style style = new Style.Builder()
        .fromUri("mapbox://styles/mapbox/streets-v12")
        .addSource(new VectorSource("local-tiles-source", localTileSet))
        .addLayer(new FillLayer("local-fill", "local-tiles-source"));

mapView.getMapAsync(map -> map.setStyle(style));

4. 本地文件权限触发的隐性校验 #

虽然不加头能加载，但加头后可能触发了更严格的文件读取校验，导致权限不足。

• 解决办法：
  • 如果瓦片存放在外部存储，确保App已经申请并获取了READ_EXTERNAL_STORAGE运行时权限。
  • 优先将瓦片存放在App内部存储（如getFilesDir()目录），避免外部存储的权限波动问题。

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