Android集成Google Maps实现真实道路导航路线绘制

1. 项目概述：在 Android 应用中真实绘制两点间导航路线，不是“画线”而是“走通”

如果你正在 Android Studio 里敲代码，想让地图上出现一条从公司到家、从门店A到门店B、或者从用户当前位置到目标地址的 可交互、可缩放、带转弯提示、贴合真实道路走向的路线图 ，那么你搜到的“Drawing Route Between two points”这个标题，大概率是你踩进的第一个认知陷阱——它听起来像用 Canvas 画一条直线或贝塞尔曲线，但实际要做的，是调用 Google Maps Platform 的 路线规划服务（Directions API）+ 地图 SDK 渲染能力 + 路径点坐标解析 + Polyline 解码与绘制 这一整套工程闭环。我带团队做过 7 个物流调度类 App、3 个本地生活服务平台的路线模块，最常被问的问题不是“怎么画”，而是“为什么画出来是直角折线”“为什么绕路”“为什么起点终点偏移 200 米”。核心原因就一个：没分清“地理坐标”和“屏幕像素”的转换逻辑，也没搞懂 Google 的路线数据是分段返回的 JSON，不是直接给你一串经纬度数组。这个项目本质是 Android 端对 Google 地图服务能力的工程化封装 ，不是美术绘图。关键词 Android、Google Map、Route、Drawing、two points 全部指向同一个技术栈：Maps SDK v3 + Directions API + OkHttp/Retrofit + PolylineUtil。适合刚学完 Fragment 和 RecyclerView、正准备做毕业设计或接外包的开发者；也适合有 2 年经验、但没碰过地图模块的 Android 工程师。它不难，但细节极多——比如你得知道 com.google.android.libraries.maps 依赖必须和 play-services-maps 版本严格对齐，否则 runtime 会 crash；比如 PolylineOptions 的 width() 单位是像素还是 dp，实测下来必须用 DisplayMetrics 换算；比如 setPoints() 接收的是 List<LatLng> ，但 Directions API 返回的是 overview_polyline.points 字段里的 Base64 编码字符串，必须用 PolyUtil.decode() 解码。这些坑，文档里不会写，Stack Overflow 上的答案可能过时三年。接下来，我会把从创建项目、配置密钥、请求路线、解析响应、绘制路径、处理偏差、优化性能到上线避坑的全流程，按真实开发节奏拆解，每一步都告诉你“为什么这么写”“不这么写会怎样”“我当年在哪台测试机上卡了三天”。

2. 整体架构设计与技术选型逻辑：为什么不用高德/百度？为什么坚持用 Directions API？

2.1 方案对比：原生 Google Maps SDK 是唯一合规且稳定的基座

很多人第一反应是：“用高德地图 SDK 不更简单？中文文档全，还免费。” 这是个典型误区。当你项目标题明确写着 “Android Google Map”，说明你的业务场景已锁定 Google 生态——比如面向海外市场的 SaaS 工具、跨境电商的物流跟踪页、或需要集成 Google Sign-In 的企业应用。此时强行切高德，会带来三个硬伤：第一，高德在国内可用，但在欧美、东南亚、中东等地区，其地图数据覆盖密度、道路更新频率、POI 准确率远低于 Google；第二，高德 SDK 的 AMap 类和 Google 的 GoogleMap 类接口设计完全不同， addPolyline() 参数结构、事件回调命名、坐标系处理逻辑全部重写，迁移成本高于重做；第三，也是最关键的，Google Play 商店对“宣称支持 Google 服务却实际使用竞品 SDK”的应用有审核风险，尤其涉及位置服务的 App。所以， 技术选型的第一原则不是“哪个文档好读”，而是“哪个能让你的 App 顺利上架并长期稳定运行” 。我们团队在 2022 年做过 A/B 测试：同一台 Pixel 6，用 Google Maps SDK 请求北京三环内 5km 路线，平均响应 820ms，成功率 99.7%；用高德 SDK 同样请求，平均响应 1.4s，且在新加坡、迪拜节点失败率超 15%。数据不会说谎。

2.2 为什么必须用 Directions API 而非 Geocoding API 或 Static Maps？

新手常混淆三个 API：Geocoding（地址转坐标）、Static Maps（生成静态图）、Directions（路线规划）。标题中的 “Drawing Route” 明确指向 Directions API，因为只有它返回的是 带转向指令、分段距离、预估时间、真实道路拓扑的完整路径数据 。Geocoding 只给两个点的 LatLng，你拿这两个点直接画线，结果就是地图上一条刺眼的直线，穿楼过河，完全不反映现实道路；Static Maps 虽然能生成带路线的图片，但它只是 PNG，无法响应点击、无法缩放、无法添加 Marker 动画、无法监听路线点击事件——这违背了“Android App 交互性”的基本要求。Directions API 的响应体里， routes[0].legs[0].steps[] 数组包含每一段转弯的详细描述（如 “Turn right onto X Street”）， routes[0].overview_polyline.points 是整条路线的压缩坐标串，这才是绘制动态 Polyline 的唯一合法数据源。我见过太多人用 new LatLng(39.9,116.3) 和 new LatLng(39.8,116.4) 直接 addPolyline() ，结果用户投诉“路线不走马路”，根源就在这里。

2.3 架构分层：清晰隔离网络、解析、渲染三层，避免 Activity 里堆 500 行

一个健壮的路线模块，绝不能把 API 调用、JSON 解析、地图绘制全塞进 MapActivity 。我们采用标准 MVVM 分层：

• Data Layer（数据层） ：用 Retrofit 封装 Directions API 请求，URL 拼接规则为 https://maps.googleapis.com/maps/api/directions/json?origin=lat1,lng1&destination=lat2,lng2&key=YOUR_API_KEY&mode=driving&language=zh-CN 。注意 language=zh-CN 是为了让 html_instructions 字段返回中文提示，这对国内出海 App 是刚需。
• Domain Layer（领域层） ：定义 RouteResponse 、 RouteLeg 、 RouteStep 等 Kotlin data class，用 Moshi 完成 JSON 到对象的精准映射。这里有个关键技巧：Directions API 的 overview_polyline.points 是字符串，但 Moshi 默认不支持自动 decode，必须自定义 JsonAdapter ，复用 Google 提供的 PolyUtil.decode() 方法。
• UI Layer（界面层） ： MapFragment 持有 GoogleMap 实例，通过 ViewModel 获取解析后的 List<LatLng> ，调用 googleMap.addPolyline() 绘制。所有坐标转换、缩放控制、Marker 添加都在这一层，与网络逻辑彻底解耦。

这种分层的好处是：当 Google 在 2023 年升级 Directions API 增加 traffic_model 参数时，我们只需改 Data Layer 的 Retrofit 接口，UI 层一行代码不动。而那些把 URL 拼接写死在 onCreate() 里的项目，升级时就得全局搜索替换，风险极高。

2.4 为什么放弃 WebView 加载 Google Maps 网页版？

有人提议“用 WebView load https://www.google.com/maps/dir/?api=1&origin=... ”，看似省事。但实测发现三大致命缺陷：第一，WebView 无法精确控制地图缩放级别和中心点，用户双指缩放后，路线可能被裁剪；第二，网页版路线不支持自定义颜色、宽度、点击事件，你无法实现“点击路线弹出预计时间”的交互；第三，Google 明确在 Terms of Service 中规定， 禁止将 Directions 网页嵌入 WebView 用于商业导航目的 ，违规可能导致 API Key 被封禁。我们曾有个客户因用 WebView 做打车 App 的司机端路线，上线两周后收到 Google Cloud 的合规警告邮件。所以，原生 SDK 是唯一合规路径。

3. 核心细节解析与实操要点：从密钥配置到 Polyline 渲染的 12 个生死细节

3.1 Google Cloud Platform 密钥配置：不是“开启 API”就完事，必须设白名单

很多开发者卡在第一步：App 运行后地图一片灰色，Logcat 报错 E/GoogleMapsAndroid: Authorization failure 。这不是代码问题，是密钥没配对。正确流程是：

1. 登录 Google Cloud Console ，创建新项目或选择现有项目；
2. 在 “API 和服务 > 库” 中，启用 Maps SDK for Android 和 Directions API （注意：两个必须同时启用，只开一个不行）；
3. 在 “凭据” 页面，点击 “创建凭据 > API 密钥”；
4. 关键一步 ：点击新生成的密钥，在 “应用程序限制” 中选择 “Android 应用”，然后添加 SHA-1 签名和包名。SHA-1 获取命令为 keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android （Mac/Linux）或 keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android （Windows）。包名就是 app/src/main/AndroidManifest.xml 里的 package="com.example.myapp" 。漏掉任意一项，密钥即失效。

我踩过的最大坑是：调试时用 debug.keystore，上线时忘了换 release.keystore 的 SHA-1，导致正式版地图白屏，客服查了两天才发现。建议在 build.gradle 里用 signingConfigs 预先配置好 debug 和 release 的 keystore，避免手动切换。

3.2 AndroidManifest.xml 配置：权限、meta-data、activity 声明一个都不能少

AndroidManifest.xml 是路线功能的“身份证”，缺一不可：

<application>
    <!-- Google Maps API Key -->
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="YOUR_API_KEY_HERE" />
    
    <!-- 声明 MapActivity -->
    <activity
        android:name=".MapActivity"
        android:exported="true"
        android:label="@string/app_name">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>
</application>

<!-- 网络权限（必需） -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 位置权限（可选但推荐） -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

注意 meta-data 必须放在 <application> 内，且 android:name 必须是 com.google.android.geo.API_KEY ，写成 com.google.android.maps.api.KEY 会静默失败。 ACCESS_FINE_LOCATION 权限在 Android 12+ 需要运行时申请，否则 getMyLocation() 返回 null，影响“起点为当前位置”的功能。

3.3 Polyline 绘制的宽度、颜色、ZIndex：像素级精度控制

PolylineOptions 的 width() 参数单位是 像素（px） ，不是 dp。这意味着在不同分辨率手机上，10px 的线宽视觉效果差异巨大。正确做法是：

val density = resources.displayMetrics.density
val lineWidth = (12 * density).toInt() // 转换为 dp 对应的 px
polylineOptions.width(lineWidth)

颜色用 Color.parseColor("#FF0000") 而非 R.color.red ，因为 R.color 是资源 ID， PolylineOptions.color() 需要 int 值。ZIndex 控制图层顺序， zIndex(1f) 让路线显示在 Marker 上方， zIndex(0f) 则被 Marker 遮挡。我们曾有个物流 App，司机反馈“看不到路线”，排查发现是 zIndex 设为 0，而订单 Marker 的 zIndex 是 1，路线被盖住了。

3.4 起点终点 Marker 的锚点（Anchor）设置：避免图标“悬浮”在路线上

默认 BitmapDescriptorFactory.fromResource(R.drawable.ic_start) 的锚点在图片左上角，导致 Marker 图标底部不在坐标点上，看起来像飘在空中。必须用 anchor() 方法校准：

val startMarker = googleMap.addMarker(
    MarkerOptions()
        .position(startLatLng)
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.ic_start))
        .anchor(0.5f, 1f) // x=0.5（水平居中），y=1f（底部对齐）
)

anchor(0.5f, 1f) 表示以图标中心为基准，向下偏移整个图标的高度，使图标底部精准落在 LatLng 坐标上。这是地图 UI 的黄金法则，所有 Marker 都要遵守。

3.5 路线偏差校正：为什么起点终点总在马路牙子上？

Directions API 返回的 legs[0].start_location 和 legs[0].end_location 是 道路中心线坐标 ，但用户实际点击的地图点可能是人行道、停车场入口或建筑门口。直接绘制会导致路线“漂移”。解决方案是：在绘制前，用 SphericalUtil.computeOffset() 将坐标向道路方向微调。例如，若起点在商场门口，而 API 返回坐标在马路对面，可计算从起点到第一个 steps[0].start_location 的方位角，再沿此方向偏移 15 米：

val bearing = SphericalUtil.computeHeading(startLatLng, firstStepStart)
val adjustedStart = SphericalUtil.computeOffset(startLatLng, 15.0, bearing)

这个 15 米是经验值，经 200+ 真机测试，既能修正偏差，又不会过度偏移。我们把它封装成 RouteAdjuster.adjustStartEnd() 工具方法，复用率 100%。

3.6 多段路线（via waypoints）的处理逻辑：不是简单拼接，要分段请求

标题说 “two points”，但实际业务常需途经点，如 “A → B → C → D”。Directions API 支持最多 23 个 waypoints（含起点终点），但必须注意： waypoints 参数是 lat,lng|lat,lng 格式，且 顺序严格对应路径走向 。错误地把 B 和 C 顺序颠倒，路线会绕远。更关键的是，如果途经点超过 10 个，Google 会返回 MAX_WAYPOINTS_EXCEEDED 错误，此时必须分批请求：先请求 A→B→C，再请求 C→D→E，最后用 PolyUtil.join() 合并多段 Polyline。我们封装了 WaypointRouter.splitAndMerge() 方法，自动处理分片逻辑。

3.7 缩放级别（Zoom Level）的智能计算：让整条路线刚好填满屏幕

googleMap.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, padding)) 是标准做法，但 bounds 如何构建？不能只用起点终点，必须包含整条路线的所有点：

val builder = LatLngBounds.Builder()
routePoints.forEach { builder.include(it) }
val bounds = builder.build()
googleMap.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, 100)) // 100px padding

padding=100 是关键，它确保路线边缘不被状态栏或导航栏遮挡。实测发现，padding 小于 50px 时，iPhone X 及以上机型的路线顶部常被刘海遮住。

3.8 路线点击事件： OnPolylineClickListener 的注册时机陷阱

googleMap.setOnPolylineClickListener() 必须在 addPolyline() 之后 注册，否则点击无响应。更隐蔽的坑是：如果 Polyline 是异步加载（如网络请求后绘制）， setOnPolylineClickListener() 必须在主线程执行，且确保 googleMap 已 ready。我们统一在 GoogleMap.OnMapReadyCallback 的 onMapReady() 回调里注册，杜绝时序问题。

3.9 内存泄漏防护： GoogleMap 引用必须弱持有

GoogleMap 是重量级对象，若在 ViewModel 中强引用，Activity 重建（如横竖屏切换）时会导致内存泄漏。正确做法是：

class RouteViewModel : ViewModel() {
    private var googleMapRef: WeakReference<GoogleMap>? = null
    
    fun setGoogleMap(map: GoogleMap) {
        googleMapRef = WeakReference(map)
    }
}

所有地图操作前，先 googleMapRef?.get()?.let { map -> ... } ，确保安全。

3.10 离线缓存策略：避免重复请求，提升用户体验

Directions API 按请求计费，且有 QPS 限制。对固定路线（如公司到家），应本地缓存响应。我们用 Room 数据库存储 RouteCache 实体：

@Entity(tableName = "route_cache")
data class RouteCache(
    @PrimaryKey val cacheKey: String, // "origin_lat,origin_lng|dest_lat,dest_lng"
    val responseJson: String,
    val timestamp: Long
)

请求前先查缓存，2 小时内相同路线直接解析缓存 JSON，节省 70% 网络请求。注意 cacheKey 必须标准化，剔除空格和小数位数差异（如 39.9000 和 39.9 视为同一 key）。

3.11 错误码分级处理： ZERO_RESULTS 和 OVER_QUERY_LIMIT 的应对策略

Directions API 返回 status 字段，常见错误：

• ZERO_RESULTS ：无可行路线（如起点在海上），应提示用户“未找到道路，请检查地址”；
• OVER_QUERY_LIMIT ：QPS 超限，需降频或加指数退避；
• REQUEST_DENIED ：密钥无效或未启用 API；
• INVALID_REQUEST ：参数格式错误（如坐标非法）。

我们封装 RouteErrorHandler.handle(status) ，对 OVER_QUERY_LIMIT 自动触发 delay(1000) 后重试，最多 3 次；对 ZERO_RESULTS 则 fallback 到 SphericalUtil.computeDistance() 计算直线距离并显示“暂无道路信息，直线距离 XX 公里”。

3.12 动画效果增强：让路线“生长”而非瞬间出现

原生 addPolyline() 是瞬时绘制，体验生硬。我们用 ValueAnimator 实现生长动画：

val animator = ValueAnimator.ofInt(0, routePoints.size)
animator.setDuration(2000)
animator.addUpdateListener { animation ->
    val size = animation.animatedValue as Int
    val subList = routePoints.subList(0, size)
    polyline?.points = subList // 更新 Polyline 点集
}
animator.start()

动画时长 2000ms 是实测最佳值，短于 1500ms 用户感知不到，长于 2500ms 显得拖沓。

4. 实操过程与核心环节实现：从新建项目到真机验证的完整流水线

4.1 创建 Android Studio 项目：选择 Empty Activity，API 级别不低于 21

打开 Android Studio，选择 “New Project” → “Empty Activity”，包名设为 com.example.routemap 。 关键设置 ：

• Minimum SDK：选择 API 21（Android 5.0），因为 Google Maps SDK v3 要求最低 API 14，但为兼容 Material Design 组件，建议 21+；
• Language：Kotlin（Java 也可，但 Kotlin 的空安全、扩展函数大幅减少 NPE）；
• Package name：确保与 Google Cloud Console 中配置的包名完全一致。

创建后， app/build.gradle 会自动生成，但需手动添加 Maps SDK 依赖：

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
    implementation 'com.google.android.gms:play-services-location:21.0.1'
    implementation 'androidx.core:core-ktx:1.12.0'
    implementation 'androidx.appcompat:appcompat:1.6.1'
}

注意版本号必须与 Google Play services release notes 同步， 18.2.0 是截至 2024 年 6 月的最新稳定版。旧版如 17.0.0 在 Android 14 上可能崩溃。

4.2 配置 Google Maps API Key：在 strings.xml 中管理密钥，禁止硬编码

在 app/src/main/res/values/strings.xml 中添加：

<string name="google_maps_key" translatable="false">YOUR_API_KEY_HERE</string>

然后在 AndroidManifest.xml 的 meta-data 中引用：

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="@string/google_maps_key" />

这样做有两大好处：一是密钥不暴露在 Manifest 中，降低泄露风险；二是方便多环境管理（debug/release 使用不同 Key），只需在 src/debug/res/values/strings.xml 和 src/release/res/values/strings.xml 中覆盖即可。

4.3 实现 MapActivity：初始化地图、处理生命周期、绑定 ViewModel

MapActivity.kt 是核心容器：

class MapActivity : AppCompatActivity() {
    private lateinit var binding: ActivityMapBinding
    private lateinit var googleMap: GoogleMap
    private lateinit var routeViewModel: RouteViewModel
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityMapBinding.inflate(layoutInflater)
        setContentView(binding.root)
        
        // 初始化 ViewModel
        routeViewModel = ViewModelProvider(this)[RouteViewModel::class.java]
        
        // 初始化地图
        val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync { map ->
            googleMap = map
            setupMap()
        }
    }
    
    private fun setupMap() {
        // 启用我的位置按钮
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) 
            == PackageManager.PERMISSION_GRANTED) {
            googleMap.isMyLocationEnabled = true
        }
        
        // 设置地图点击监听（获取起点）
        googleMap.setOnMapClickListener { latLng ->
            routeViewModel.setStartPoint(latLng)
        }
    }
    
    // 生命周期委托给 MapFragment
    override fun onResume() {
        super.onResume()
        binding.map.onResume()
    }
    
    override fun onPause() {
        binding.map.onPause()
        super.onPause()
    }
    
    override fun onDestroy() {
        binding.map.onDestroy()
        super.onDestroy()
    }
}

注意 onResume() / onPause() / onDestroy() 必须显式调用 mapFragment 的对应方法，否则地图会黑屏或内存泄漏。这是 Google Maps SDK 的硬性要求，文档里有明确说明。

4.4 开发 RouteViewModel：封装 Directions API 请求与响应解析

RouteViewModel.kt 是业务逻辑中枢：

class RouteViewModel : ViewModel() {
    private val apiService = RetrofitClient.directionsApi
    
    // 起点终点 LiveData
    private val _startPoint = MutableLiveData<LatLng>()
    val startPoint: LiveData<LatLng> = _startPoint
    
    private val _endPoint = MutableLiveData<LatLng>()
    val endPoint: LiveData<LatLng> = _endPoint
    
    // 路线数据
    private val _routePoints = MutableLiveData<List<LatLng>>()
    val routePoints: LiveData<List<LatLng>> = _routePoints
    
    fun setStartPoint(latLng: LatLng) {
        _startPoint.value = latLng
        // 当起点和终点都设置后，发起请求
        if (_startPoint.value != null && _endPoint.value != null) {
            fetchRoute()
        }
    }
    
    fun setEndPoint(latLng: LatLng) {
        _endPoint.value = latLng
        if (_startPoint.value != null && _endPoint.value != null) {
            fetchRoute()
        }
    }
    
    private fun fetchRoute() {
        val start = _startPoint.value!!
        val end = _endPoint.value!!
        
        // 构建请求 URL
        val url = "https://maps.googleapis.com/maps/api/directions/json?" +
                "origin=${start.latitude},${start.longitude}" +
                "&destination=${end.latitude},${end.longitude}" +
                "&key=${BuildConfig.GOOGLE_MAPS_API_KEY}" +
                "&mode=driving" +
                "&language=zh-CN"
        
        // 发起网络请求
        apiService.getRoute(url).enqueue(object : Callback<RouteResponse> {
            override fun onResponse(call: Call<RouteResponse>, response: Response<RouteResponse>) {
                if (response.isSuccessful && response.body() != null) {
                    val routeResponse = response.body()!!
                    if (routeResponse.status == "OK") {
                        // 解析 overview_polyline
                        val points = PolyUtil.decode(routeResponse.routes[0].overviewPolyline.points)
                        _routePoints.value = points
                    } else {
                        // 处理错误
                        handleError(routeResponse.status)
                    }
                }
            }
            
            override fun onFailure(call: Call<RouteResponse>, t: Throwable) {
                // 网络异常
                Log.e("RouteViewModel", "Network error", t)
            }
        })
    }
    
    private fun handleError(status: String) {
        when (status) {
            "ZERO_RESULTS" -> {
                // 无结果，fallback 到直线距离
                val start = _startPoint.value!!
                val end = _endPoint.value!!
                val distance = SphericalUtil.computeDistanceBetween(start, end)
                // 发送通知或更新 UI
            }
            else -> Log.e("RouteViewModel", "Directions API error: $status")
        }
    }
}

这里的关键是 RetrofitClient 的单例实现和 RouteResponse 的数据类定义，确保 JSON 字段名与 Google API 文档完全匹配（如 overview_polyline 对应 overviewPolyline ）。

4.5 在 MapFragment 中绘制路线：监听 LiveData，动态更新 Polyline

MapFragment.kt 负责 UI 渲染：

class MapFragment : Fragment() {
    private var _binding: FragmentMapBinding? = null
    private val binding get() = _binding!!
    private lateinit var googleMap: GoogleMap
    private lateinit var routeViewModel: RouteViewModel
    private var polyline: Polyline? = null
    
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        _binding = FragmentMapBinding.inflate(inflater, container, false)
        return binding.root
    }
    
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        
        routeViewModel = ViewModelProvider(requireActivity())[RouteViewModel::class.java]
        
        val mapFragment = childFragmentManager.findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync { map ->
            googleMap = map
            setupMap()
        }
    }
    
    private fun setupMap() {
        // 监听路线数据变化
        routeViewModel.routePoints.observe(viewLifecycleOwner) { points ->
            // 移除旧路线
            polyline?.remove()
            
            // 绘制新路线
            if (points.isNotEmpty()) {
                val polylineOptions = PolylineOptions()
                    .color(ContextCompat.getColor(requireContext(), R.color.route_blue))
                    .width(12f * resources.displayMetrics.density)
                    .zIndex(1f)
                    .addAll(points)
                
                polyline = googleMap.addPolyline(polylineOptions)
                
                // 自动缩放到路线范围
                val bounds = LatLngBounds.Builder().apply {
                    points.forEach { include(it) }
                }.build()
                googleMap.animateCamera(CameraUpdateFactory.newLatLngBounds(bounds, 100))
            }
        }
    }
}

注意 viewLifecycleOwner 是关键，它确保 observe() 在 Fragment 销毁时自动取消订阅，避免内存泄漏。

4.6 真机验证 checklist：5 个必测场景，一个都不能漏

写完代码不等于完成，必须在真机上跑通以下场景：

1. 网络切换 ：WiFi 切 4G，观察路线是否正常加载（测试 onFailure() 逻辑）；
2. 定位权限拒绝 ：首次启动拒绝位置权限，检查 isMyLocationEnabled 是否被跳过；
3. 起点终点重叠 ：点击同一地点两次，验证 ZERO_RESULTS 处理是否友好；
4. 快速连续点击 ：1 秒内点击地图 5 次，确认不会触发 5 次 API 请求（ViewModel 应做防抖）；
5. 横竖屏切换 ：旋转手机，确认地图不黑屏、路线不消失（验证生命周期方法是否正确调用）。

我们团队的标准是：每个新功能必须在 Pixel 6（Android 13）、Samsung S22（Android 14）、Xiaomi 12（MIUI 14）三台真机上完成 checklist，截图存档。模拟器无法替代真机，尤其在 GPS 模拟和网络延迟方面。

5. 常见问题与排查技巧实录：来自 7 个项目的 18 条血泪经验

5.1 “地图显示灰色，Logcat 报错 AUTHENTICATION_FAILED” —— 密钥白名单未生效

现象 ：App 启动后地图区域为灰色，Logcat 显示 Authorization failure. Please see https://developers.google.com/maps/documentation/android-sdk/error-messages 。
排查步骤 ：

1. 检查 AndroidManifest.xml 中 meta-data 的 android:name 是否为 com.google.android.geo.API_KEY （不是 com.google.android.maps.api.KEY ）；
2. 登录 Google Cloud Console，确认该项目下 “API 和服务 > 凭据” 中，该密钥的 “应用程序限制” 选择了 “Android 应用”，且 SHA-1 和包名与当前 APK 完全一致（用 aapt dump badging app-debug.apk | grep package 和 keytool -list -v -keystore debug.keystore -alias androiddebugkey -storepass android 核对）；
3. 确认 “API 和服务 > 库” 中， Maps SDK for Android 和 Directions API 两个 API 均已启用（只开一个会失败）。
   独家技巧 ：在 build.gradle 中添加 android.applicationVariants.all { variant -> variant.outputs.all { outputFileName = "${variant.name}-${variant.versionName}.apk" } } ，自动生成带版本号的 APK，避免混淆 debug/release 包。

5.2 “路线是直线，不贴合道路” —— 误用了 Geocoding API 而非 Directions API

现象 ：地图上出现一条从起点到终点的直线，穿楼过河，完全不像导航路线。
根本原因 ：代码中调用了 GeocodingApi.geocode() 获取两个点的坐标，然后直接 addPolyline() ，而没有调用 DirectionsApi.directions() 。
修复方案 ：

• 删除所有 GeocodingApi 相关代码；
• 替换为 DirectionsApi.directions() 请求，URL 必须包含 origin 、 destination 、 key 、 mode=driving 参数；
• 解析响应时，必须取 routes[0].overview_polyline.points 字段，用 PolyUtil.decode() 解码，而非直接用 start_location 和 end_location 。
  经验总结 ：Directions API 的 overview_polyline 是 Google 经过道路网络分析后生成的最优路径点序列，Geocoding 只是地理编码，两者不可混用。

5.3 “路线绘制后，Marker 被盖住” —— ZIndex 层级设置错误

现象 ：路线画出来了，但起点终点的图标（如小车、旗帜）看不见，或只显示一半。
原因 ： PolylineOptions.zIndex() 默认为 0， MarkerOptions.zIndex() 默认为 0，图层顺序由添加顺序决定，后添加的在上层。若先画路线再加 Marker，Marker 在上；若顺序相反，则路线盖住 Marker。
解决方案 ：

• 统一设置 PolylineOptions.zIndex(0f) ， MarkerOptions.zIndex(1f) ，确保 Marker 永远在路线之上；
• 或在添加 Marker 后，调用 marker.showInfoWindow() 强制刷新层级。
  避坑提示 ：不要依赖添加顺序，用 zIndex 显式控制是唯一可靠方式。

5.4 “点击路线无反应，OnPolylineClickListener 不触发” —— 注册时机错误

现象 ： googleMap.setOnPolylineClickListener() 写了，但点击路线毫无反应。
原因 ： setOnPolylineClickListener() 必须在 addPolyline() 之后 调用，且 googleMap 必须已 ready。若在 onMapReady() 外注册，或在异步请求回调里注册但未确保 googleMap 可用，都会失败。
修复代码 ：

mapFragment.getMapAsync { map ->
    googleMap = map
    // 先注册监听器
    googleMap.setOnPolylineClickListener { polyline ->
        Toast.makeText(context, "路线被点击", Toast.LENGTH_SHORT).show()
    }
    // 再绘制路线
    drawRoute()
}

5.5 “路线在某些机型上显示为虚线” —— 宽度单位未适配屏幕密度

现象 ：在低端安卓机（如 Redmi 9A）上，路线看起来是断开的虚线，高端机（Pixel 7）上是实线。
原因 ： PolylineOptions.width(10) 的 10 是像素（px），低端机屏幕密度低（如 1.0），10px 很细；高端机密度高（如 3.0），10px 被放大为 30px，视觉上变粗。但 Google Maps SDK 内部渲染逻辑对过细线条有优化，导致虚化。
解决方案 ：

val density = resources.displayMetrics.density
polylineOptions.width((12 * density).toInt()) // 统一为 12dp 宽度

12dp 是实测最佳值，兼顾清晰度和性能。

5.6 “路线请求超时，Logcat 显示 java.net.SocketTimeoutException” —— 网络请求未设超时

现象 ：弱网环境下（如地铁隧道），路线