Swift MapKit自定义瓦片与折线缩放移动时断裂问题求助

异常表现 #

开发支持CarPlay的导航应用时，地图上的自定义瓦片与多色折线出现以下问题：

• 地图移动或缩放时，折线与自定义瓦片在瓦片边缘断裂
• 折线偶尔被绘制得更宽，异常画面需等待系统缓慢刷新后才消失，会停留数秒

成因分析 #

1. 折线渲染逻辑缺陷 #

• 未适配Tile分段绘制机制：CustomGradientPolylineRenderer自行遍历点绘制路径，没有利用MKPolylineRenderer基于Tile的分段渲染逻辑，导致跨Tile的折线被截断。
• 线宽计算完全颠倒：当前用(lineWidth - 1) / zoomScale计算实际线宽，逻辑错误——MKPolylineRenderer的lineWidth是逻辑像素，绘制时需要乘以zoomScale转换为屏幕物理像素，缩放时计算错误直接导致线宽异常。
• 逐段绘制产生缝隙：drawGradientLine中每段线段单独调用strokePath，相邻线段之间会因线帽/连接方式出现缝隙，在Tile边缘更明显。
• 裁剪判断精度不足：将MKMapRect转成CGRect后判断交集，存在坐标精度损失，导致部分本该绘制的区域被跳过。
• 重复绘制叠加：调用了super.draw，默认绘制逻辑与自定义绘制重复，叠加后加重线宽异常。

2. 自定义瓦片加载问题 #

• Overlay重复移除添加：setupTileRenderer每次都移除旧的MapOverlay再添加新的，地图移动时会触发瓦片重新加载，导致短暂空白/断裂。
• Tile加载未做优化：MapOverlay仅重写了url(forTilePath:)，未处理Tile加载的缓存、异步回调逻辑，地图快速移动时瓦片加载滞后，出现边缘断裂。

3. 重绘触发不及时 #

自定义绘制逻辑没有主动触发局部重绘，依赖系统默认的刷新机制，系统刷新慢时异常画面会持续停留。

解决方案 #

一、修复折线渲染逻辑 #

修改CustomGradientPolylineRenderer，适配Tile绘制机制，修正线宽计算，优化渐变绘制：

import MapKit
import Foundation

class CustomGradientPolylineRenderer: MKPolylineRenderer {
    override func draw(_ mapRect: MKMapRect, zoomScale: MKZoomScale, in context: CGContext) {
        // 用MKMapRect直接判断交集，避免CGRect精度损失
        let lineMapRect = self.polyline.boundingMapRect
        guard MKMapRectIntersectsRect(mapRect, lineMapRect) else { return }
        guard let polyLine = self.polyline as? GradientRoutePolyline else { return }
        
        let actualLineWidth = self.lineWidth * CGFloat(zoomScale)
        context.setLineCap(.round)
        context.setLineJoin(.round) // 解决线段连接缝隙
        
        // 绘制白色底线路径（复用已生成的path，避免自行遍历点）
        context.addPath(self.path)
        context.setLineWidth(actualLineWidth)
        context.setStrokeColor(UIColor.white.cgColor)
        context.strokePath()
        
        // 绘制渐变线路径：用CGGradient实现平滑渐变，而非逐段设色
        let gradientColors = polyLine.colors.map { $0.cgColor } as CFArray
        guard let gradient = CGGradient(colorsSpace: CGColorSpaceCreateDeviceRGB(), colors: gradientColors, locations: polyLine.locations) else { return }
        
        context.addPath(self.path)
        context.setLineWidth(actualLineWidth - 5 * CGFloat(zoomScale)) // 基于缩放调整内层线宽
        // 用路径的bounding box作为渐变起点终点，适配折线方向
        let pathBounds = self.path.boundingBoxOfPath
        context.saveGState()
        context.clip(to: pathBounds)
        context.drawLinearGradient(gradient, start: CGPoint(x: pathBounds.minX, y: pathBounds.minY), end: CGPoint(x: pathBounds.maxX, y: pathBounds.maxY), options: [.drawsBeforeStartLocation, .drawsAfterEndLocation])
        context.restoreGState()
        
        // 移除super.draw，避免重复绘制
    }
}

同时优化GradientRoutePolyline的渐变位置计算，按路径长度比例分配（原按点索引的方式不够精准）：

// 在GradientRoutePolyline的便利init中替换locations计算逻辑
var cumulativeDistances: [CGFloat] = [0]
for i in 1..<pointArray.count {
    let prevCoord = pointArray[i-1]
    let currCoord = pointArray[i]
    let distance = CLLocation(latitude: prevCoord.latitude, longitude: prevCoord.longitude)
        .distance(from: CLLocation(latitude: currCoord.latitude, longitude: currCoord.longitude))
    cumulativeDistances.append(cumulativeDistances.last! + CGFloat(distance))
}
let totalDistance = cumulativeDistances.last!
self.locations = cumulativeDistances.map { $0 / totalDistance }

二、优化自定义瓦片加载 #

1. 复用MapOverlay，避免重复移除添加：

private func setupTileRenderer() {
    let skin = AccountService.shared.userSettings.mapSettings.skin.rawValue
    let template = "\(ConfigKey.TILE_URL.value)\(skin)_en_v2/{z}/{x}/{y}.png?v=3"
    
    // 查找已存在的MapOverlay，更新urlTemplate而非重新创建
    if let existingOverlay = mapView.overlays.first(where: { $0 is MapOverlay }) as? MapOverlay {
        existingOverlay.urlTemplate = template
        existingOverlay.maximumZ = Int(maxZoomLevel)
        mapView.reloadOverlay(existingOverlay)
    } else {
        let tileOverlay = MapOverlay(urlTemplate: template)
        tileOverlay.canReplaceMapContent = true
        tileOverlay.maximumZ = Int(maxZoomLevel)
        mapView.insertOverlay(tileOverlay, at: 0)
    }
}

2. 可选：添加Tile缓存逻辑：

class MapOverlay: MKTileOverlay {
    override func url(forTilePath path: MKTileOverlayPath) -> URL {
        var tileUrl = urlTemplate!.replacingOccurrences(of: "{z}", with: "\(path.z)")
        tileUrl = tileUrl.replacingOccurrences(of: "{x}", with: "\(path.x)")
        tileUrl = tileUrl.replacingOccurrences(of: "{y}", with: "\(path.y)")
        return URL(string: tileUrl)!
    }
    
    // 自定义缓存逻辑，优先读取本地缓存
    override func loadTile(at path: MKTileOverlayPath, result: @escaping (Data?, Error?) -> Void) {
        let url = self.url(forTilePath: path)
        // 此处可添加本地缓存读取逻辑，比如从FileManager读取缓存文件
        URLSession.shared.dataTask(with: url) { data, _, error in
            DispatchQueue.main.async {
                result(data, error)
            }
        }.resume()
    }
}

三、触发及时重绘 #

监听地图区域变化，主动触发局部重绘：

// 在你的地图ViewController中添加MKMapViewDelegate实现
extension YourMapViewController: MKMapViewDelegate {
    func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
        // 针对折线overlay触发重绘
        if let polylineOverlay = mapView.overlays.first(where: { $0 is GradientRoutePolyline }) {
            mapView.setNeedsDisplay(for: polylineOverlay)
        }
        // 针对瓦片overlay触发重绘（可选）
        mapView.setNeedsDisplay()
    }
}

额外CarPlay适配提示 #

CarPlay的地图渲染有特殊性能限制，建议：

• 对路径点进行抽稀优化，减少折线的点数量
• 使用合适分辨率的瓦片，避免过大的Tile文件
• 关闭不必要的地图特效，降低渲染负载

内容的提问来源于stack exchange，提问作者Ákos Morvai