osmdroid 接入谷歌影像底图：瓦片 URL 拼接与多域名轮询实战

摘要：osmdroid 接入谷歌影像底图时，直接 setTileSource 往往花屏或空白，因为引擎默认的瓦片 URL 拼法与谷歌要求的 x/y/z 参数不一致。本文讲透瓦片坐标 (x, y, zoom) 与 URL 模板的契约关系，教你重写 URL 拼接方法并做多域名轮询规避限流，附完整 Kotlin 代码，接任何"花式瓦片服务"都通用。

文章导读

适用引擎/版本：osmdroid 6.x
完整源码：https://gitcode.com/qq_16064871/android_osmdroid_maplibre

一、问题长什么样

假设需求是"接入谷歌影像瓦片"，你会尝试这样写：

kotlin 复制代码

// 自以为接入完成，但瓦片地址拼错了
val source = XYTileSource(
    name = "GoogleImage",
    minZoom = 0,
    maxZoom = 22,
    tileSizePixels = 256,
    imageFilenameEnding = "",
    baseUrl = "http://mts1.google.com/vt/lyrs=y&hl=x-local"
)
mapView.setTileSource(source)

一运行，第一屏是花的，或者干脆一片空白。你反复检查，地址明明是对的，凭什么？

答案藏在引擎的一个细节里：XYTileSource 的基类会按自己的规则把瓦片坐标拼进 URL 尾部 ，而谷歌的服务要求的是 x/y/z 这种带名字的参数。引擎默认拼出来的东西，和谷歌要的不一样------所以你得接管 URL 拼接。

二、根因：瓦片 URL 是一个"模板 + 坐标"的契约

地图引擎渲染底图时，会为屏幕上的每个瓦片计算一个 (x, y, zoom) 三元组------这就是瓦片坐标 ：zoom 是缩放级别，x/y 是该级别下瓦片在网格里的行列号。引擎知道坐标，但它不知道你的服务商希望 URL 长什么样。

于是"瓦片源"这个抽象，本质上就是一件简单的事：

拿到 (x, y, zoom)，拼出一个能拿到这张图的 URL。

内置的服务，引擎已经写好了拼接规则；自定义的服务，拼接规则由你接管。所以问题的根因不是"谷歌瓦片地址难找"，而是"引擎没有为每一种服务内置拼接规则，你得自己实现这个'契约'"。

三、实现：接管 URL 拼接，并做好多域名

1. 重写 URL 拼接：把坐标按服务要求拼进去

关键在重写"取 URL"的方法，从瓦片索引里拆出 x/y/zoom，再按服务的参数名拼好：

kotlin 复制代码

// 自定义瓦片源：把引擎算好的瓦片坐标，拼成服务端认识的 URL
class GoogleImageSource : XYTileSource(
    name = "GoogleImage",
    minZoom = 0,
    maxZoom = 22,
    tileSizePixels = 256,
    imageFilenameEnding = "",
    baseUrl = arrayOf("http://mts1.google.com/vt/lyrs=y&hl=x-local")
) {
    override fun getTileURLString(tile: Long): String {
        val x = MapTileIndex.getX(tile)
        val y = MapTileIndex.getY(tile)
        val zoom = MapTileIndex.getZoom(tile)
        // 服务端要求 x/y/z 命名参数，与引擎默认拼法不同
        return "$baseUrl&x=$x&y=$y&z=$zoom"
    }
}

这里 baseUrl 和拼接是分离的：baseUrl 只描述"服务 + 样式"，真正的坐标在拼接阶段动态补上。

2. 多域名轮询：规避服务端限流

在线瓦片服务通常提供多个镜像域名（如 mts1/2/3）。如果只写死一个域名，请求集中在单点，容易被限流。做法是把它们都塞进 base 地址列表：

kotlin 复制代码

// 多域名：引擎会按某个策略轮询，避免单点被打爆
val source = XYTileSource(
    name = "GoogleImage",
    minZoom = 0,
    maxZoom = 22,
    tileSizePixels = 256,
    imageFilenameEnding = "",
    baseUrl = arrayOf(
        "http://mts1.google.com/vt/lyrs=y&hl=x-local",
        "http://mts2.google.com/vt/lyrs=y&hl=x-local",
        "http://mts3.google.com/vt/lyrs=y&hl=x-local"
    )
) {
    override fun getTileURLString(tile: Long): String {
        val x = MapTileIndex.getX(tile)
        val y = MapTileIndex.getY(tile)
        val zoom = MapTileIndex.getZoom(tile)
        return "$baseUrl&x=$x&y=$y&z=$zoom"
    }
}

注意：虽然拼接只用了"当前这一个域名"的 baseUrl，但把全部域名列进去，引擎在派发请求时会分散到这些域名上，这是在线瓦片接入的通用姿势。

3. 按图层名切换：影像 vs 矢量

同一个服务往往有"影像"和"矢量"两种样式，差异只是 URL 里的一个参数（lyrs=y 是影像、lyrs=m 是矢量）。可以定义两个瓦片源，用图层名做路由：

kotlin 复制代码

// 图层名 -> 瓦片源 的路由表
fun tileSourceFor(layerName: String): TileSource = when (layerName) {
    "影像底图" -> googleImageSource
    "矢量底图" -> googleVectorSource
    else -> defaultSource
}

// 切换底图：一行代码，但背后的瓦片调度器会整体换血
mapView.setTileSource(tileSourceFor(currentLayerName))

setTileSource 之所以重要，是因为它不止换了 URL 模板，还会触发瓦片调度器重新拉取当前视野的瓦片------所以"切换底图"天然自带刷新，你不用额外手动 invalidate。

四、升华：一切瓦片服务都是"坐标到 URL 的映射"

把谷歌这个例子抽象掉，你会得到一个通用结论：

任何在线瓦片服务，无论它是影像、矢量、还是某个私有协议，本质上都是给一个 (x, y, zoom)，返回一个可下载图片的 URL。差别只在：参数叫什么、域名有几个、是否有 token、是否需要签名。

所以对接一个新服务，你只需要问四个问题：

最小/最大级别是多少？（决定缩放范围约束）
瓦片尺寸是多少？（常见 256）
域名有几个？（决定是否要多域名轮询）
URL 参数叫什么、要不要 token / 签名？（决定拼接规则）

把这四件事问清楚，"接入任何瓦片源"就从"抄代码碰运气"变成"填空"。

五、总结

瓦片源的本质是**"(x, y, zoom) → 可下载 URL"的契约**，内置服务已实现，自定义服务要自己实现拼接。
自定义瓦片源要重写 URL 拼接方法，把引擎算好的瓦片坐标，按服务端要求的参数名拼好。
多域名轮询是规避在线瓦片限流的通用做法，把镜像域名都列进 base 地址即可。
影像 / 矢量等样式差异往往只是一个 URL 参数，用图层名路由表切换最干净。
对接任何新瓦片服务，只需确认级别范围 / 瓦片尺寸 / 域名数 / 参数与签名四件事。

完整工程源码见：https://gitcode.com/qq_16064871/android_osmdroid_maplibre

上一篇： $天地图接入 osmdroid：影像/矢量/注记四类服务与级别限制详解$ (04_osmdroid_在线瓦片源天地图.md) ·