企业官网建设流程全解析

1. 接入高德定位前，先把这几件事搞明白

我做打卡类App那会儿，被定位功能折腾过好几个晚上。明明照着官方文档一步一步集成了高德定位SDK，代码也没报错，但真机跑起来就是收不到回调，或者定位到了但是坐标放到地图上偏出去几百米。后来把整个流程理了一遍才发现，问题往往不在SDK本身，而在接入前没搞清楚的几个底层概念上。这篇就把高德地图获取定位从0到1的完整链路、常见坑和排查思路一次性说透。

先说定位SDK和地图SDK的关系。很多人以为接了一个高德SDK就能又是地图又是定位，其实它们是两套独立的东西。地图SDK负责渲染地图、画覆盖物、做搜索；定位SDK只负责一件事——拿到当前设备的经纬度、精度、地址描述这些信息。两者可以配合使用，也可以只接定位SDK。如果你的业务只需要“知道用户在哪”，比如打卡、签到、附近的人，那就没必要把整个地图SDK引进来，包体积能省不少。

再说坐标系。高德地图用的是一套叫做GCJ-02的偏移坐标系，因为国内地图行业的合规要求，原始GPS坐标在公开地图上是经过偏移处理的。这意味着你直接用手机GPS模块拿到的经纬度画到高德地图上，位置会偏出几十米甚至几百米。高德定位SDK返回的坐标已经是GCJ-02，可以直接叠加在高德地图上；但如果你用的是系统API或者第三方GPS硬件返回的WGS-84坐标，画上去就会偏。我见过不少新手在这上面浪费大量时间，以为是地图画错了，其实是坐标系没转换。

还有一点容易忽略：高德定位并不是单纯靠GPS，它是GPS、Wi-Fi、基站、蓝牙多源融合定位。GPS在开阔室外最准，但室内基本废掉；Wi-Fi定位在城区室内反而比GPS更实用，代价是误差可能到几十米甚至上百米；基站定位覆盖广但误差最大。理解这个融合机制很重要，因为后文排查“为什么定位不准、为什么半天没有回调”时，很多问题都得回到这个最原始的定位原理去解释。

这篇文章适合谁看？如果你是第一次在高德开放平台创建应用、第一次把定位权限和SDK代码接到自己项目里，或者遇到了“定位失败、定位不准、坐标偏移、权限申请无效”这类问题，按下面的步骤走一遍，基本能把问题定位到具体环节。

2. 环境与Key配置：最不起眼却最容易翻车的环节

高德定位接入的第一道门槛不是代码，是API Key。我接手过好几个项目，定位一直失败，日志里有10001之类的认证错误，最后排查下来无一例外是Key和应用的包名/签名对应不上。高德平台校验Key的逻辑是这样的：Key本身是一串字符串，但它绑定了一个应用的包名和签名SHA1值，这三个必须完全匹配才能认证通过。

2.1 Android端的Key绑定逻辑

Android上配置Key有两个方式：一是在AndroidManifest.xml里加meta-data，二是代码里初始化AMapLocationClient.setApiKey()。我更推荐用meta-data，因为Key是配置信息，不该硬编码在代码里，方便不同环境切换。

<application> <meta-data android:name="com.amap.api.v2.apikey" android:value="你的Key" /> </application>

但这里真正的坑在于包名和SHA1。包名不是你看得顺眼的那个名字，而是build.gradle里applicationId最终编译出来的包名，包括多版本渠道后缀，比如com.example.app和com.example.app.debug是不同的。签名的SHA1也分debug和release两套，而且如果在开发机上换了电脑或者重新生成过keystore，SHA1就变了，平台那边不会自动更新，必须手动去后台改。

查看SHA1的命令很简单：

keytool -v -list -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

release签名换成自己的keystore路径和密码即可。拿到SHA1后，在高德开放平台对应应用里把调试版SHA1、发布版SHA1都填上，用哪个签名就打勾哪个，稳一点的做法是两个都填，避免切换环境时突然认证失败。

2.2 iOS端的Key与Info.plist配置

iOS端同样要申请Key，但校验逻辑简单些，主要是Bundle ID匹配。真正让不少人在iOS上卡住的，是忘了配置定位权限描述。系统在弹窗申请定位权限前，会先检查Info.plist里有没有对应的用途说明字符串，如果缺失，App可能在申请权限时直接崩溃，或者在后台日志里报“This app has attempted to access privacy-sensitive data without a usage description”。

配置项是这两行：

<key>NSLocationWhenInUseUsageDescription</key> <string>需要获取你的位置信息用于标记打卡地点</string> <key>NSLocationAlwaysAndWhenInUseUsageDescription</key> <string>需要持续获取你的位置信息用于轨迹记录</string>

只做前台定位就只配WhenInUse，需要后台持续定位再加Always。苹果审核对后台定位查得很严，用途说明必须和实际功能一致，描述别写得太含糊。

2.3 一个真实的Key排查案例

之前某项目在联调环境定位正常，一打包发布版就返回Key错误，排查了很久。后来发现是发布签名用了一个测试用的keystore，而高德后台只配置了正式发布的SHA1，测试签名的SHA1没填。像这种线上线下行为不一致的问题，优先检查平台配置里SHA1是否完整覆盖了所有签名环境。

我把常见的Key配置问题按症状整理在下面这张表里，便于对照：

3. 权限申请与系统定位开关：Android高版本适配怎么做

如果Key配置没问题，下一个高频翻车点就是权限。iOS上一篇提过，Android这边更复杂，因为从6.0开始运行时权限、从10开始后台定位限制、从12开始精确定位模糊化，每一层都可能拦住定位结果。

3.1 运行时权限申请的正确姿势

高德定位需要以下权限：

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

COARSE是粗略定位，FINE是精确定位，建议两个都申请。Android 6.0以上必须动态申请，在代码里调用requestPermissions，但这里有个细节：高德定位SDK在初始化时不会主动替你申请权限，如果用户拒绝，你后续调用定位时会一直失败。所以规范的流程应该是：进入定位页面先检查权限，没有就发起申请，拿到授权后再启动定位。

用Activity Result API写这种流程会干净很多，避免onRequestPermissionsResult的回调地狱。Kotlin侧大致这么写：

private val locationPermissionLauncher = registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { result -> val fine = result[Manifest.permission.ACCESS_FINE_LOCATION] == true val coarse = result[Manifest.permission.ACCESS_COARSE_LOCATION] == true if (fine || coarse) { startLocation() } else { // 提示用户去设置页打开权限 } } private fun checkLocationPermission() { val fineGranted = ContextCompat.checkSelfPermission( this, Manifest.permission.ACCESS_FINE_LOCATION ) == PackageManager.PERMISSION_GRANTED val coarseGranted = ContextCompat.checkSelfPermission( this, Manifest.permission.ACCESS_COARSE_LOCATION ) == PackageManager.PERMISSION_GRANTED if (fineGranted || coarseGranted) { startLocation() } else { locationPermissionLauncher.launch( arrayOf( Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION ) ) } }

3.2 Android高版本的新限制

Android 10及以上如果要在后台获取定位，需要额外申请ACCESS_BACKGROUND_LOCATION权限，而且这个权限不能和前台权限一起申请，得分开引导用户到设置里单独授权。大部分业务用不到后台定位，如果只是App在前台使用，别乱申请后台定位权限，否则应用市场审核容易被质疑。

Android 12开始，系统设置里给用户提供了“大概位置”选项。用户选了大概位置后，哪怕你申请了FINE权限，系统实际也只授予粗略定位能力。高德定位在这种情况下通常能返回坐标，但精度会明显变差，这属于用户主动选择，代码层没有太好的办法，只能通过提示用户去系统设置里选择“精确位置”来优化。

Android 14还引入了一个新要求：如果App在后台使用前台服务并且需要定位，需要在前台服务声明里指定foregroundServiceType为location，否则运行时会被系统拦下来。这个问题在跑持续定位场景时会遇到。我建议做定位需求之前，先明确自己的App只在用户能看到界面时定位，还是需要在后台持续定位，这两种场景的配置复杂度完全不同。

3.3 定位开关：比你想的更隐蔽的问题

权限拿到手不代表就能定位，手机系统里还有两级开关：一级是“位置服务总开关”，二级是“单个应用的定位权限”。很多开发者只盯权限，忽略了用户把总开关关掉的情况。高德SDK在定位开关关闭时，通常不会立刻报错，而是回调一直在等待，表现就是“拿不到定位结果”。

我当时做测试时也踩过这个坑：在开发者选项里误开了“模拟地理位置”，导致定位结果一直固定在某地，还以为代码写错了。所以调试时如果发现定位结果异常固定，或者跟真实位置差得离谱，先去检查开发者选项里的模拟位置设置，再检查系统定位服务是否开启。

4. 单次定位与持续定位：API选择背后要考虑什么

高德定位SDK最核心的对象是AMapLocationClient，所有定位能力都靠它。调用方式本身不复杂，难的是搞清楚什么时候用单次定位、什么时候用持续定位，以及怎么避免定位回调一直不触发。

4.1 单次定位的应用场景

打卡、签单、提交当前位置这类业务，拿到一次定位结果就够了，没必要让定位模块持续工作。单次定位会省电不少。高德SDK里设置单次定位是这样的：

val option = AMapLocationClientOption().apply { isOnceLocation = true isNeedAddress = true } locationClient = AMapLocationClient(this).apply { setLocationOption(option) setLocationListener { aMapLocation -> if (aMapLocation != null && aMapLocation.errorCode == 0) { val lat = aMapLocation.latitude val lng = aMapLocation.longitude val address = aMapLocation.address // 业务处理 } else { // 定位失败，aMapLocation.errorCode是错误码 } // 单次定位，拿到结果后可以主动停止 locationClient?.stopLocation() } startLocation() }

代码里有个容易忽略的点：isOnceLocation = true之后，定位结果返回仍然会走onLocationChanged回调，但回调次数不会严格保证只有一次。有些情况下系统会把缓存定位先回调一次，后面再回调一次更精准的定位。所以业务上不要假定“第一次回调就是最佳结果”，最好根据aMapLocation.accuracy来判断精度，在可接受范围内再使用。

4.2 持续定位的应用场景

轨迹记录、骑行导航这类场景需要持续获取位置。这时要把isOnceLocation设为false，并根据业务需求设置定位间隔。高德SDK的定位间隔通过setInterval控制，单位毫秒，默认2秒有点激进，大多数业务5到10秒足够了。频繁定位带来的电量消耗和CPU占用是实打实的，尤其屏幕常亮的场景下会发热。

val option = AMapLocationClientOption().apply { isOnceLocation = false interval = 5000 isNeedAddress = false // 持续定位一般不需要逆地理编码，关了省电 isKillProcess = false }

顺带说一下isNeedAddress。这个字段控制要不要在定位结果里附带省市区街道和详细地址，依赖逆地理编码网络请求，非常耗时耗电。如果你只需要经纬度或者业务上可以从经纬度反查地址，就别开这个字段，否则每个定位点都会多一次网络请求，定位回调明显变慢。

4.3 回调不触发，怎么下手查

这是提问率最高的一类问题：明明调用了startLocation()，onLocationChanged就是不执行。结合我排查的经验，按照概率排序，原因通常是这样：

权限没有授予。这是最容易被忽略的，因为IDE有时候不会报错，只有运行到定位那一步才静默失败。先去设置里确认应用是否有定位权限。

手机的定位服务总开关或GPS开关没打开。很多国产ROM在快速设置栏里有关闭“定位”的快捷按钮，关了之后应用层拿不到任何位置。

网络定位所需的联网权限缺失。Wi-Fi和基站定位需要访问网络，如果工程里漏了INTERNET权限，定位SDK在室外还能靠GPS勉强返回，室内基本废掉。

单次定位的回调已经发生过一次，但你没注意到。部分场景下用户重复进入页面多次创建了AMapLocationClient，旧实例的监听器与页面生命周期不一致，导致你以为回调没触发。排查时可以打日志看生命周期，确认onCreate里是否重复初始化了定位客户端。

5. 实测定不了位、定位不准的完整排查链路

这一节重点写定位失败和定位不准的排查方法论。我给自己定了一个固定的排查顺序，每次遇到定位问题，按这个链条从上到下过一遍，基本能在一个小时内定位到根因。

5.1 第一步：先确认基础环境，别急着怀疑SDK

拿到一个“定位失败”的反馈，我第一步一定会问/验证这些：

• 手机系统定位开关是否打开？
• App的定位权限是否被拒绝或者设置为“仅使用时允许”？后台定位场景是否被限制？
• 当前环境是室内还是室外？室内GPS本来就不可靠，必须靠Wi-Fi和基站。
• 网络是否可用？网络定位必须联网。
• 是否在模拟器上测试？模拟器上定位默认返回的是模拟位置，不是真实GPS，高德SDK在模拟器上的表现和真机差异很大。

上述任何一项不满足，都不该先怀疑代码问题。尤其是模拟器，我在模拟器上遇到过定位一直返回某个国外坐标的情况，其实是模拟器默认位置没设置。真机测试才是正路。

5.2 第二步：顺着调用链检查代码

基础环境没问题，再看代码：

• 是否在AndroidManifest.xml正确配置了Key？报错日志有没有Key error字样？
• AMapLocationClient是否在子线程初始化？高德定位SDK要求在主线程初始化，否则会有异常。
• 是否设置了LocationOption和LocationListener？有人只初始化了client，忘了设置监听，自然没有回调。
• startLocation()是否被调用？有时候业务分支提前return了，代码根本走不到这里。
• onDestroy()里有没有调用locationClient.onDestroy()释放资源？重复创建定位客户端会导致内存浪费，也可能导致旧回调串台。

日志要打全。我会在onLocationChanged的第一行打一条日志，把errorCode、latitude、longitude、accuracy、locationType全部打出来。这样每次定位结果一目了然。高德的errorCode == 0表示成功，非0表示失败，不同错误码对应不同失败原因。收到错误码不要慌，先去看高德官方文档里的错误码表，大部分问题都在里面写着。

5.3 第三步：定位不准的误差来源与调优

定位成功但位置不准，是另一类很让人头疼的问题。首先要理解一个现实：手机定位本身就是估算，不是精确值。GPS的精度通常在5到10米，Wi-Fi定位的误差几十米到几百米不等，基站定位误差更夸张。如果用户在室内、地铁、地下车库，任何SDK都拿不到精准位置。

高德定位返回的结果里，accuracy字段代表精度半径，单位是米。拿到一个定位结果后，我的建议是先判断accuracy是否满足业务要求。例如打卡场景要求半径50米以内，那么accuracy > 50的结果可以直接丢弃，等待下一次回调。这样虽然可能多等几秒，但不会出现用户明明在A店打卡，却因为定位漂移被打到B店的问题。

还有一类情况是“定位结果跳跃”：用户静止不动，两秒后结果跳出了几十米。这可能因为SDK先返回了缓存定位，后续才返回实时定位。高德SDK默认会对定位结果做缓存，缓存定位的locationType值会是0或者固定值。如果业务对实时性要求高，可以在LocationOption里关掉缓存，避免拿旧位置充数。

结合项目和经验，我把高频症状和对应排查方向做了个速查表：

5.4 一次典型的完整排错过程

分享一个具体排查过程：某项目反馈“用户在小程序里点打卡，一直转圈拿不到定位”。我先远程看日志发现errorCode一直是4，对应定位失败。然后查了真机系统定位开关，正常；查了权限，也开放了。最后定位到代码里，发现打卡页面在onCreate里初始化了定位客户端，但权限请求弹窗是在另一个Activity里异步完成的，用户授权返回后，定位还没开始启动，页面已经进入等待状态。也就是说“回调不触发”不是因为SDK有问题，而是业务流的先后顺序乱了。改成授权成功后再初始化并启动定位，问题立刻消失。

这类问题在业务代码里很常见。定位模块本身很简单，难的是和页面生命周期、权限流程、用户交互糅合在一起后的各种时序问题。所以排查时不要只盯着SDK日志，也要看自己的业务代码执行顺序。

6. iOS端特有差异与坐标转换：这些细节别等上线后才发现

Android和iOS在高德定位上的接入流程相似，但iOS有几个特有差异，常见于新手适配时忽略，导致同一套代码Android正常、iOS偏航。

6.1 坐标系：GCJ-02与WGS-84不能混用

前面说过高德返回的是GCJ-02坐标，iOS系统自带的CLLocationManager返回的是WGS-84原始坐标。如果你的App里同时用到了高德地图和系统的定位能力，必须做坐标转换，否则用户的实际位置会偏移几十米。

高德提供了一个转换工具，可以将WGS-84坐标转成GCJ-02：

CLLocationCoordinate2D amapCoord = AMapCoordinateConvert(CLLocationCoordinate2DMake(latitude, longitude), AMapCoordinateTypeWGS84);

转换后拿到的坐标才能用于高德地图展示。反过来，如果你要从高德地图上取一个点拿给后端做距离计算，而后端用的是WGS-84，也需要转回去。这个转换逻辑不是简单的加减偏移，而是一套非线性算法，千万别自己在代码里写死偏移量，误差不稳定。

6.2 iOS定位的坑

iOS定位第一个坑是模拟器。模拟器默认不带真实GPS，需要手动在菜单里设置模拟位置。很多人在模拟器上测试完觉得没问题，一上真机就发现定位权限弹窗逻辑不对。我的建议很直接：定位功能从第一天起就在真机上测，模拟器只用来验证UI和地图显示。

第二个坑是权限弹窗的触发机制。iOS定位权限弹窗只能触发一次，用户选了“不允许”之后，后续再想弹窗只能引导用户去系统设置里修改。所以第一次触发弹窗的时机很重要，最好在用户明确知道为什么要定位的时候再申请，一打开页面就弹窗被拒率很高。

第三个坑是后台定位。如果App切到后台还想定位，除了权限描述要写Always，还要在Xcode的Signing & Capabilities里开启Background Modes中的Location updates，两者缺一不可。而且即便都开了，iOS系统对后台定位频次仍然有阈值限制，做不到Android那样自由指定间隔的持续高频定位。如果你做的是轨迹记录类App，建议前后台切换时调整定位策略，后台时降低定位频率，避免过度消耗电量。

高德SDK在iOS上初始化比较简单，通常在AppDelegate里配置Key即可。但注意，AMapLocationManager的delegate必须强持有，否则会被系统释放导致回调消失。这是一个非常隐蔽的问题，跑着跑着定位不动了，多半和这有关。

7. 写在最后：我用高德定位的几点体会

定位功能看上去简单，做起来其实是一个系统性工程。SDK的调用只是最后一步，前面还有Key体系、权限适配、坐标系理解、真机调试验证、业务时序设计等一堆前置条件。任何一个环节掉链子，表象都会集中体现在“定位失败”或“定位不准”上。

我自己现在做定位相关的需求时，会先写一个固定的检查清单：先确认是前台定位还是后台定位，再确认目标坐标系，接着配好权限和Key，最后再写SDK调用。代码写完后一定在真机上跑一轮，把错误码和精度日志打出来。这样做下来，出问题的概率大大降低。

最后分享一个小技巧：调试定位问题时，把定位结果画到地图上而不是只打日志。打个点是不够的，最好以定位点为圆心画一个精度圈，这样accuracy到底有多大、坐标有没有漂移，一眼就能看出来。很多“定位不准”的问题，光看经纬度是发现不了的，画出来才直观。

希望这篇能帮你少走一些弯路。高德定位本身不复杂，把它背后的机制搞清楚，遇到问题时就不会再一头雾水了。