企业官网建设流程全解析

简介：《腾讯地图定位》资源是一套完整的Android定位项目工程，面向需要接入地图与位置服务的移动端开发者，解决从SDK初始化、动态权限申请到定位结果展示的全流程问题。工程基于腾讯位置服务SDK编写，包含清晰的Java源码、XML界面与AndroidManifest配置，可帮助初学者掌握高精度、省电等定位模式的选择依据，以及定位延迟、室内信号弱等常见问题的处理策略。压缩包共76个文件，核心包含5个Java源码、16个class文件、16个XML布局与配置文件、6个jar依赖库、6个so架构库（覆盖armeabi-v7a与x86），另有19张png图标资源及可直接安装运行的apk安装包；整体大小仅4.16MB，目录结构整洁，便于按资源类型检索学习。目前已有728人学习下载。对正在评估腾讯地图定位能力、或希望快速搭建可运行Demo的Android开发者而言，这份资源提供了从源码阅读到安装验证的完整参照，能显著缩短定位功能集成的前期摸索时间。

1. 腾讯地图定位：Android 定位这件事，比你想的更依赖选型

腾讯地图定位，是我在多个 LBS 项目里反复对比后留下来的一套 Android 定位方案。它最大的价值不是“能拿到经纬度”——系统定位接口也能做到，而是它在室内、高架桥下、Wi-Fi 信号杂乱这些糟糕环境里，依然能通过基站、Wi-Fi、GPS 混合策略给出一个可用的结果，冷启动速度也明显优于裸调系统接口。很多做轨迹上报、签到打卡、门店服务的开发者，最初都在LocationManager和各厂商 SDK 之间反复横跳，最后发现真正要解决的是“拿不到、拿得慢、拿得飘”这三个问题。这篇笔记就从接入准备讲起，把初始化、单次与连续定位、参数选型、高频踩坑和进阶策略一次说透。

2. 接入前的三件套：Key 申请、运行时权限与清单配置

2.1 定位 Key 的申请与校验链路

腾讯地图定位 SDK 要求每个应用绑定一个独立 Key，这个 Key 和应用包名、签名证书的 SHA1 是一一对应的。常见做法是在腾讯位置服务控制台创建应用，填写 Android 包名和签名 SHA1，生成 Key 后配置进工程。

我第一次接入时偷懒，直接复制了官方 Demo 里的 Key，结果回调里永远是错误码。原因在于控制台校验的是应用签名，官方 Demo 的 Key 只在官方签名下才能通过校验，换到自己的包名和签名上必然失败。这个校验链路是独立于 Android 权限体系的，就算你把所有权限都声明齐全，Key 不对照样拿不到坐标。

所以接入的第一步不是在 Android Studio 里写代码，而是先去控制台把 Key 申请下来，并且保存好签名信息。后续如果你切换了发布签名（比如从 debug 签名换到 release 签名），必须回控制台更新 SHA1，否则线上版本会突然全部定位失败——这个坑我在 2.1.1 小节里还会展开讲。

2.2 AndroidManifest 权限声明与版本适配

定位权限是这套 SDK 能工作的前提。Android 6.0 之后权限分为安装时授权和运行时授权两类，其中精确定位ACCESS_FINE_LOCATION和粗略定位ACCESS_COARSE_LOCATION属于危险权限，必须在运行时动态申请。

<!-- AndroidManifest.xml --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <!-- Android 10+ 后台定位，如不需要可去掉 --> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

清单文件里需要声明网络和 Wi-Fi 状态权限，因为腾讯地图定位 SDK 的混合定位策略依赖网络请求基站信息和 Wi-Fi 指纹库。ACCESS_BACKGROUND_LOCATION是 Android 10（API 29）新增的权限，如果你的应用需要在退到后台后继续上报位置（比如轨迹记录类应用），必须在清单里声明，并且在运行时和前台权限分开申请。

这里有一个容易忽略的点：从 Android 11 开始，系统对后台定位权限的申请策略变得更严格，用户在授权弹窗里只能选择“仅在使用时允许”，后台权限需要通过设置页引导开启。所以如果你做的是后台轨迹上报，产品层面要提前设计引导流程，不能只靠一个requestPermissions就指望拿到全部权限。

2.3 工程依赖引入与运行时权限申请

定位 SDK 的依赖坐标在腾讯位置服务官方文档里可以找到，通常是一个com.tencent.map.geolocation开头的 Maven 坐标，按官方文档替换成当前最新稳定版即可。

// build.gradle (app) dependencies { // 版本号以腾讯位置服务控制台公布的当前稳定版为准 implementation 'com.tencent.map.geolocation:TencentLocationSdk-open:latest' }

引入依赖之后不要急着初始化，先做一次运行时权限申请，确认用户授权后再进入定位流程。下面这段代码处理了 Android 6.0 以上的运行时权限申请逻辑。

// MainActivity.java private static final int REQ_LOCATION_PERMISSION = 100; private void checkPermissionAndLocate() { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { // 精确定位和粗略定位一起申请，注意后台定位权限需要单独处理 String[] permissions = { Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION }; if (checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { requestPermissions(permissions, REQ_LOCATION_PERMISSION); return; } } startLocation(); } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode == REQ_LOCATION_PERMISSION) { if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) { startLocation(); } else { // 拒绝后建议引导去设置页，否则混合定位只能退化为基站级别 Toast.makeText(this, "定位权限被拒绝，无法获取位置", Toast.LENGTH_SHORT).show(); } } }

逻辑说明：checkPermissionAndLocate里判断了系统版本，Android 6.0 以下不需要运行时申请，直接进入定位；6.0 以上先检查再申请。onRequestPermissionsResult里拿到授权结果后，才真正调用startLocation()。

参数说明：REQ_LOCATION_PERMISSION自定义请求码，用来在回调里区分是哪一次权限请求的结果。注意ACCESS_FINE_LOCATION和ACCESS_COARSE_LOCATION必须放在同一个申请请求里，因为这两个权限在系统里属于同一权限组，一次弹窗就能全选。

3. 从单次定位到连续定位：核心 API 的使用与回调设计

3.1 初始化定位会话与请求对象

腾讯地图定位 SDK 的入口是TencentLocationManager，它是单例，整个应用生命周期里只需要获取一次。定位请求参数通过TencentLocationRequest对象配置，每次调用定位都需要传一个配置好的实例。

// LocationHelper.java public class LocationHelper { private TencentLocationManager locationManager; public LocationHelper(Context context) { locationManager = TencentLocationManager.getInstance(context); // SDK 默认返回 GCJ-02 坐标系，国内地图展示不需要额外转换 } public void startSingleLocation(TencentLocationListener listener) { // create() 会生成一份默认参数的请求对象 TencentLocationRequest request = TencentLocationRequest.create(); // requestLevel 决定回调里附带多少逆地理编码信息，详见第 4 章 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); // 单次定位不关心间隔，设个默认值即可 request.setInterval(0); locationManager.requestLocationData(request, listener); } }

逻辑说明：TencentLocationManager.getInstance(context)拿到全局单例，内部负责管理各种定位源。TencentLocationRequest.create()生成默认请求，setRequestLevel配置返回的附加信息级别，setInterval(0)表示不启用定时更新。

参数说明：REQUEST_LEVEL_NAME表示在经纬度之外额外返回街道、区县等名称信息。如果你的业务只需要坐标，用REQUEST_LEVEL_GEO或对应最低级别，可以减少一次逆地理编码请求，定位速度更快、也省电。SDK 里具体常量名以源码注释为准，含义分几个档位，从纯经纬度到附带 POI 信息不等。

3.2 单次定位：回调、错误码与超时处理

单次定位是签到、打卡、门店导航这类场景的核心需求。它的调用方式很直接，但是回调不是同步返回的，而是异步回调在TencentLocationListener.onLocationChanged里。

// 单次定位请求示例 locationHelper.startSingleLocation(new TencentLocationListener() { @Override public void onLocationChanged(TencentLocation location, int errorCode, String reason) { if (errorCode == 0 && location != null) { double lat = location.getLatitude(); double lng = location.getLongitude(); float accuracy = location.getAccuracy(); String provider = location.getProvider(); // provider 通常返回 gps / network / cell，用于判断定位来源 Log.d("Location", "lat=" + lat + ", lng=" + lng + ", accuracy=" + accuracy + ", provider=" + provider); } else { // errorCode 非 0 表示定位失败，reason 里有可读描述 Log.e("Location", "locate failed: " + errorCode + ", " + reason); } } @Override public void onStatusUpdate(String s, int i, String s1) { // GPS 状态变化回调，一般用于展示卫星数量 } });

逻辑说明：onLocationChanged是核心回调，errorCode == 0才表示定位成功。成功时从TencentLocation对象里取经纬度、精度和定位来源；失败时打印错误码和原因，便于排查。onStatusUpdate是 GPS 模块状态变化通知，业务上通常用不到。

参数说明：accuracy的单位是米，数值越小代表定位精度越高。GPS 定位在城市开阔地带通常能到 5~20 米，纯基站定位可能在 200~1000 米之间。如果你的业务对精度有要求，回调里可以加一个阈值判断，超过阈值就丢弃结果并重新发起定位。

这里要特别提醒：单次定位请求发出后，如果长时间没有回调，比如到了室内、GPS 被遮挡，SDK 并不会自动超时，需要业务侧自己加一个延时任务，比如 10 秒内没拿到结果就提示用户“定位超时，请移动到开阔区域”。否则用户会一直看到加载动画，体验很差。我一般会在发起请求时同时启动一个CountDownTimer，回调成功或失败时取消。

3.3 连续定位：更新频率、生命周期与停止时机

连续定位常用于轨迹记录、实时配送、运动健康类应用。setInterval参数决定了相邻两次回调的最小时间间隔，单位是毫秒。这里有个常见的理解误区：设置 5000 并不意味着每 5 秒一定回调一次，而是说两次回调的间隔不少于 5 秒，具体回调时机还受定位源返回速度影响。

// 连续定位：每 5 秒一次回调 TencentLocationRequest request = TencentLocationRequest.create(); request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); request.setInterval(5000); locationManager.requestLocationData(request, listener); // 页面销毁或不需要定位时，必须及时停止 @Override protected void onDestroy() { super.onDestroy(); locationManager.removeUpdates(listener); }

逻辑说明：requestLocationData在传入带setInterval的请求对象后，SDK 会按设定的间隔周期性回调。removeUpdates用来停止连续定位，必须在onDestroy、onStop等生命周期节点调用，否则定位服务一直在后台运行，电量消耗非常明显。

参数说明：interval的设置要结合业务场景。轨迹记录类应用，骑行场景 3~5 秒比较合适，步行场景 5~10 秒，驾车场景还要考虑转弯点的采集密度，一般建议 3 秒以内。间隔越大越省电，但轨迹的平滑度会下降，两条定位点之间直线距离可能超过几十米。此外，连续定位开始后如果屏幕灭掉，部分厂商系统会主动休眠，导致回调中断，这类问题通常需要结合前台服务或高德/腾讯的厂商辅助定位来规避。

4. 参数选型：定位级别、坐标系和场景模式如何匹配业务

4.1 定位级别不是精度开关，而是数据附带量开关

很多初学者会把REQUEST_LEVEL_*理解成“精度档位”，认为级别越高定位越准。实际上这个参数控制的是回调里附带的逆地理编码信息量——纯经纬度、街道名称、区县名称，还是附近 POI 列表，和定位精度完全无关。精度取决于当前环境的 GPS 信号强度和 Wi-Fi/基站指纹库的覆盖密度。

// 不同业务场景的 requestLevel 选择 // 只需要坐标 + 时间: 用最低级别，减少网络请求 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_GEO); // 需要显示街道名称的签到应用 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); // 需要区县、市级信息的统计类应用 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_ADMIN_AREA);

逻辑说明：级别从低到高，SDK 在拿到坐标后还会额外向逆地理编码服务发起一次请求，把坐标翻译成可读地址。这对定位本身的耗时没有影响，因为坐标是并行返回的，地址信息随后跟上。但你要知道，如果业务只需要坐标，设成高级别等于白白多一次网络开销。

参数说明：选择级别的依据只有一个——你的业务在回调里需要展示什么。地图打点只需要经纬度；签到打卡需要街道；后台数据统计需要区县行政区划。不要为了“以防万一”设成 POI 级别，那个数据量很大，而且大部分字段根本用不到，反而增加分析负担。

4.2 GCJ-02 与 WGS-84：坐标系选错的后果

国内地图服务的坐标系基本都被加密偏移过，腾讯地图定位 SDK 默认返回 GCJ-02（火星坐标系），这是国家测绘标准，所有国内地图厂商的底图都基于这个坐标系。如果你的应用展示地图用的也是腾讯地图或高德地图，直接使用默认坐标系即可，地图打点位置是准确对齐的。

// 业务需要原始 GPS 坐标（如涉外应用）时显式切换坐标系 // TencentLocationManager 提供坐标类型切换方法 locationManager.setCoordinateType(TencentLocationManager.COORDINATE_TYPE_WGS_84);

逻辑说明：setCoordinateType在初始化后调用一次即可，切换后所有定位回调里的经纬度都会按指定坐标系输出。默认值是 GCJ-02，不调用任何方法就保持默认。

参数说明：COORDINATE_TYPE_WGS_84对应国际标准的 WGS-84 坐标系，它是 GPS 芯片输出的原始坐标。这里最常踩的坑是：业务方从定位 SDK 拿到 GCJ-02 坐标，却直接传给使用 WGS-84 底图的海外地图组件，导致点位偏移几百米。反过来，把 WGS-84 坐标直接画在国内底图上，也会出现明显的道路偏移。坐标系转换涉及火星坐标加密算法，网上有大量转换公式，但一定要搞清楚”底图用哪个坐标系”再动手，坐标系选错直接导致所有点位飘移。

4.3 场景模式与请求间隔：省电和时效性的平衡

定位间隔和定位模式是定位耗电的最大变量。下表整理了常见业务场景的推荐配置，直接抄作业基本不会翻车。

参数说明：interval = 0只适用于单次定位场景，调用一次只返回一次结果。连续定位场景如果设置 0，SDK 可能以最快速度连续回调，这在大多数业务里不是你要的效果，反而会在短时间内消耗大量电量。

还有一个值得注意的点：腾讯地图定位 SDK 的混合定位本身会同时启用 GPS 和网络定位，但在 GPS 信号弱的环境下，SDK 会自动退化为基站/Wi-Fi 定位。这个退化过程是黑匣子，不对外暴露详细状态，你能看到的就是location.getProvider()返回值变了。如果 provider 从 gps 变成 network，说明当前环境信号差，UI 上可以提示用户移动位置，但不要在这个节点反复重启定位请求，那样只会让耗电加倍。

5. 腾讯地图定位避坑：五个高频问题的排查记录

5.1 Key 校验失败：回调一直返回错误码

现象：定位回调始终返回非 0 错误码，reason 里提示 key 错误或鉴权失败，权限已经全部授予，网络也正常。

原因：控制台配置的包名或 SHA1 与实际应用不一致。常见于过了几天后重新生成了签名文件，或者在测试机和发布包之间切换了签名配置。另一个可能原因是 Key 在 Manifest 里配置不对，某些版本的 SDK 会从meta-data标签里读 Key，标签名写错也会触发同样的错误。

解决：先用keytool -list -v -keystore your.keystore导出当前签名的 SHA1，与控制台配置逐字符对比，重点检查字母大小写和冒号分隔格式。然后在 Manifest 中确认 Key 配置的meta-data名称和 SDK 要求的完全一致。如果你用的是自动打包方案，不同渠道签名不同，也要确保每个渠道包的 Key 都单独申请过。

5.2 Android 10+ 后台定位失效

现象：应用退到后台 1~2 分钟后，定位回调彻底停止，回到前台又恢复。

原因：Android 10 引入了ACCESS_BACKGROUND_LOCATION后台定位权限，且它的授权方式必须单独申请，普通权限弹窗无法覆盖。部分厂商系统还会在国内 ROM 上额外加一层“禁止后台定位”的开关，即使你申请了权限，用户没有在设置里放开也是白搭。

解决：在 Android 10 以上的版本，除了申请前台定位权限，还要申请后台定位权限。申请时机建议在用户进入轨迹记录功能时，通过引导文案让用户去设置页开启后台定位权限。同时要检测厂商系统设置里的“自启动”和“后台限制”，这两项在国内 ROM 上是独立于标准权限体系的，系统不会弹窗询问，只能引导用户手动修改。

5.3 模拟器里永远拿不到定位结果

现象：在 Android 模拟器里运行项目，定位回调一直超时或者报错，换成真机就正常。

原因：模拟器没有真实的 GPS 模块，也没有真实的基站和 Wi-Fi 指纹数据，腾讯地图定位 SDK 的混合定位策略在模拟器里基本是废的。这不是代码问题，也不是 Key 问题。

解决：开发阶段用adb shell给模拟器注入一个模拟位置源，或者在模拟器的扩展设置里手动指定经纬度。但注意，SDK 内部可能对模拟位置源做了检测，某些版本会拒绝返回模拟位置。最稳妥的做法是定位相关功能直接在真机上调试，测试时到室外开阔区域验证 GPS 表现，室内验证 Wi-Fi/基站定位表现。模拟器只适合调试 UI 逻辑，不适合验证定位链路。

5.4 混淆构建后定位回调不触发

现象：debug 包定位正常，release 包（开了 minifyEnabled）装上之后，Key 没有报错，权限也正常，但定位回调就是不触发。

原因：混淆规则把定位 SDK 里的类名或方法名重写了，SDK 内部通过反射拿到回调类，被混淆后反射失败，回调链路就断了。SDK 官方一般会提供混淆配置，但很多项目组接入时没有把官方 proguard 规则完整贴进去。

解决：在proguard-rules.pro里加入定位 SDK 的 keep 规则，至少需要保留 SDK 的根包路径。以下是一份保底配置。

# proguard-rules.pro # 保留定位 SDK 的所有类 -keep class com.tencent.map.geolocation.** { *; } -keepattributes Signature -keepattributes *Annotation* -dontwarn com.tencent.map.geolocation.**

逻辑说明：-keep class强制保留指定包路径下所有类不被混淆，-keepattributes保留注解和签名信息，-dontwarn抑制缺失类警告。具体包名以官方混淆文档为准，如果你接的版本包名有变化，按实际源码包路径替换，但保底思路是一样的。

参数说明：这里面最核心的是第一条，{ *; }表示保留所有成员，包括内部类。如果你的项目还用了 R8 全量优化，建议把com.tencent.map.geolocation.**同时加入consumer-rules里，避免库模块被二次裁剪。

5.5 定位跳点与精度漂移

现象：连续定位过程中，坐标点偶尔跳到几百米外，画出来的轨迹出现明显的“飞点”。

原因：定位源切换时带来的精度回退，比如从 GPS 平滑过渡到 Wi-Fi 定位的瞬间，基站定位给出的初始点误差可能很大。此外，城市峡谷环境（高楼密集区）会引入多径效应，GPS 信号反射后计算出的坐标本身就偏了。

解决：在回调里加精度阈值过滤，accuracy大于某个值的丢弃，等下一次有效回调。同时利用 SDK 返回的时间戳和上一有效点做速度校验，如果两点之间的距离除以时间间隔超过了合理速度，比如步行应用超过 6km/h，判定为飞点并丢弃或做平滑处理。我一般在定位回调里串联一个 3 点滑动滤波，取中间点作为绘制坐标，轨迹稳定性会明显改善。

6. 把定位体验做扎实：缓存优先、省电策略与精度校验

定位 SDK 本身只负责给你坐标，但用户感知到的“定位体验好不好”，取决于你在 SDK 之上怎么设计。这里分享三个我每个项目都用的固定套路。

第一个是缓存优先。冷启动进入应用时，定位往往需要 1~3 秒才能回调，这段时间地图上如果什么都没有，用户会觉得“卡”。我一般会把上次定位成功的坐标存入本地，启动时先用缓存坐标渲染界面，再异步发起新的定位请求，回调成功且精度更好时再刷新地图。

// 启动时先用缓存撑住 UI，再异步刷新 LocationCache cache = LocationCache.getInstance(this); TencentLocation last = cache.getLastLocation(); if (last != null) { updateMap(last); // 先用上一次的坐标渲染 } locationHelper.startSingleLocation(new TencentLocationListener() { @Override public void onLocationChanged(TencentLocation location, int errorCode, String reason) { if (errorCode == 0 && location != null && location.getAccuracy() < 80) { cache.save(location); // 只有高精度结果才覆盖缓存 updateMap(location); // 新坐标到位，刷新地图 } } // onStatusUpdate 省略 });

逻辑说明：LocationCache是业务侧自建的存储类，内部用 SharedPreferences 保存经纬度、精度和时间戳。这里的关键设计有两个：一是缓存坐标必须带上时间戳，超过 10 分钟就不能再用了，否则用户可能看到了一个“昨天的位置”；二是只有精度小于 80 米的结果才写入缓存，避免把飞点存下来污染下次启动。

第二个是省电策略。连续定位的interval按业务场景已经做了区分，但还有一个容易被忽略的点——屏幕熄灭时主动降低定位频率，或者干脆停止定位，等应用回到前台再恢复。我接轨迹类项目时，会注册一个ScreenBroadcastReceiver，系统灭屏就调removeUpdates，点亮屏幕再重新发起定位。这种实现方式既能保住轨迹的大体完整，又能把夜间待机耗电降一个量级。

第三个是精度校验的统一封装。不要在业务层到处写if (accuracy < 80)这种散装逻辑，而是把校验收敛到定位管理器里，提供一个onResult的包裹回调，把精度过滤、飞点判断、时间戳校验都在这一层做掉，上层拿到的一定是干净坐标。这样以后要调整阈值，改一处就够了。

这套组合是我从早期项目里一路踩出来的。最早我在一个巡检模拟项目里直接用原始回调，用户走完一整条街轨迹却是一条断裂的折线——飞点、缓存过期、后台停止全遇到了。从那以后，我每次接入定位 SDK 都强制先写一个最小验证工程，确认 Key、权限、回调链路通了再开始业务代码，然后每接一个新业务场景，先把定位级别、间隔、缓存策略这三件事定下来再写 UI。这个习惯救了我很多次，希望帮到你。

本文还有配套的精品资源，点击获取