简介这份资源是面向iOS初中级开发者的地图定位入门示例工程围绕Core Location与MapKit两大框架演示定位权限申请、精度与距离过滤参数设置、位置更新回调处理、停止定位省电以及地图上展示用户位置等基础能力适合需要在实际项目中快速接入定位功能的开发者参考。压缩包共23个文件以m与h源码文件为主辅以plist配置、strings本地化、json与工程配置等类型整体约42KB体量轻便易于通读。目前已有267人学习下载。工程内含可直接运行的示例项目与说明文档读者可对照代码理解CLLocationManager的初始化与代理回调流程掌握Info.plist权限描述键的配置要点并借鉴地图追踪模式的用法为后续扩展地理围栏、逆地理编码等功能打下基础。1. 从一次“定位漂移”说起这个 iOS 地图定位 Demo 到底能干什么去年帮一个做同城跑腿的朋友排查问题用户下单后骑手端地图上那个小蓝点总是慢半拍明明人已经到小区门口了定位还停在两百米外的路口。翻代码发现他们直接拿CLLocationManager的startUpdatingLocation原始坐标往地图上怼既没做精度过滤也没处理坐标系转换更没考虑定位权限被降级成“模糊位置”的情况。这类问题在 iOS 地图定位开发里太常见了而这个iOS 地图定位 Demo就是把这些坑一次性趟平的参考实现它把 CoreLocation 定位、MapKit 地图展示、权限申请、坐标纠偏、模拟器位置模拟这几块串成一条完整链路适合刚接触 iOS 地图模块的新手照着跑通也适合需要快速搭一个定位骨架的老手直接拿去改。下面我按“能干什么 → 怎么跑 → 怎么改”的顺序把这个 Demo 拆开讲。2. 项目骨架与技术选型为什么是 CoreLocation MapKit 这套组合2.1 技术栈拆解原生框架优先的取舍这个 Demo 没有引入任何第三方地图 SDK全部基于苹果原生框架。核心就两块CoreLocation负责拿到设备经纬度、海拔、速度、航向这些原始数据MapKit负责把坐标渲染成地图并画标注。选原生而不是第三方理由很实际——定位精度和权限模型跟系统版本强绑定第三方 SDK 往往要额外申请一堆权限、包体也大而这个 Demo 的定位是“教学 骨架”原生方案依赖最少、跑起来最快。模块框架职责定位管理CoreLocation权限申请、持续定位、单次定位、精度过滤地图渲染MapKit地图展示、区域设置、大头针标注坐标转换自写工具类WGS-84 与 GCJ-02 互转界面UIKit地图视图 定位按钮 状态标签这里有个容易被忽略的点iOS 系统返回的坐标是WGS-84标准而国内地图服务包括部分 MapKit 在国内的底图用的是GCJ-02加密坐标。Demo 里专门放了一个坐标转换工具类就是为了解决“定位点跟地图底图对不上”这个经典问题。常见做法是定位拿到 WGS-84 后先转 GCJ-02 再上地图反过来做逆地理编码时再转回去。2.2 目录结构一个能直接拖进工程的模块划分Demo 的目录不复杂但分层清晰照着这个结构建文件基本不会乱MapLocationDemo/ ├── App/ │ ├── AppDelegate.swift │ └── SceneDelegate.swift ├── Location/ │ ├── LocationManager.swift // 定位核心封装 │ └── CoordinateConverter.swift // 坐标转换工具 ├── Map/ │ ├── MapViewController.swift // 地图主界面 │ └── MapAnnotation.swift // 自定义标注模型 ├── Permission/ │ └── PermissionHelper.swift // 权限状态检查与引导 └── Resources/ └── Info.plist // 权限描述配置LocationManager.swift是整个 Demo 的心脏它把CLLocationManager的代理回调、精度过滤、错误处理都收在一个类里外部只暴露start()、stop()和几个闭包回调。MapViewController.swift只负责 UI 和地图区域更新不直接碰定位逻辑。这种“定位与展示分离”的写法后面二次开发时换地图引擎或者加轨迹绘制都不用动定位层。2.3 权限配置Info.plist 里那两行不能少跑不起来最常见的原因就是权限描述没配。iOS 13 之后定位权限分“使用期间”和“始终”两档Demo 默认用“使用期间”需要在Info.plist里加keyNSLocationWhenInUseUsageDescription/key string需要获取您的位置以在地图上显示当前位置/string如果后续要加后台持续定位还得补NSLocationAlwaysAndWhenInUseUsageDescription并在 Xcode 的 Signing Capabilities 里勾上 Background Modes 的 Location updates。注意描述文案不能空着苹果审核会直接拒本地跑虽然不拦但养成写清楚的习惯没坏处。3. 定位核心链路从权限申请到坐标上图的完整代码3.1 LocationManager 封装代理回调怎么收才不乱直接在主控制器里实现CLLocationManagerDelegate是新手最容易翻车的地方——回调散落在各处精度过滤和错误处理混在一起。Demo 的做法是单独封一个类把代理方法收进来对外只给闭包import CoreLocation final class LocationManager: NSObject, CLLocationManagerDelegate { private let manager CLLocationManager() var onLocationUpdate: ((CLLocation) - Void)? var onError: ((Error) - Void)? override init() { super.init() manager.delegate self manager.desiredAccuracy kCLLocationAccuracyBest manager.distanceFilter 5.0 // 移动超过 5 米才回调省电 } func requestPermission() { manager.requestWhenInUseAuthorization() } func start() { manager.startUpdatingLocation() } func stop() { manager.stopUpdatingLocation() } // 代理权限变化 func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) { switch manager.authorizationStatus { case .authorizedWhenInUse, .authorizedAlways: start() case .denied, .restricted: onError?(NSError(domain: Location, code: 1, userInfo: [NSLocalizedDescriptionKey: 定位权限被拒绝])) default: break } } // 代理定位回调 func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) { guard let latest locations.last else { return } // 过滤掉精度过差的点避免地图上乱跳 guard latest.horizontalAccuracy 0, latest.horizontalAccuracy 50 else { return } onLocationUpdate?(latest) } func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) { onError?(error) } }这段代码有几个参数值得说清楚。desiredAccuracy设成kCLLocationAccuracyBest是精度优先耗电也高实际产品里如果只是展示当前位置用kCLLocationAccuracyHundredMeters就够。distanceFilter 5.0表示设备移动超过 5 米才触发回调这是省电的关键设成 0 会疯狂回调。horizontalAccuracy是水平精度半径单位米负数表示坐标无效大于 50 米的点直接丢掉——这就是解决开头说的“小蓝点乱飘”的第一道过滤。3.2 坐标转换WGS-84 转 GCJ-02 的那几十行定位拿到的CLLocation.coordinate是 WGS-84直接丢给国内底图会偏移几百米。Demo 里的转换工具类核心逻辑如下struct CoordinateConverter { private static let a 6378245.0 // 长半轴 private static let ee 0.00669342162296594323 // 偏心率平方 static func wgs84ToGcj02(_ coordinate: CLLocationCoordinate2D) - CLLocationCoordinate2D { let lat coordinate.latitude let lon coordinate.longitude // 国外坐标不偏移 if lon 72.004 || lon 137.8347 || lat 0.8293 || lat 55.8271 { return coordinate } var dLat transformLat(lon - 105.0, lat - 35.0) var dLon transformLon(lon - 105.0, lat - 35.0) let radLat lat / 180.0 * .pi var magic sin(radLat) magic 1 - ee * magic * magic let sqrtMagic sqrt(magic) dLat (dLat * 180.0) / ((a * (1 - ee)) / (magic * sqrtMagic) * .pi) dLon (dLon * 180.0) / (a / sqrtMagic * cos(radLat) * .pi) return CLLocationCoordinate2D(latitude: lat dLat, longitude: lon dLon) } private static func transformLat(_ x: Double, _ y: Double) - Double { var ret -100.0 2.0 * x 3.0 * y 0.2 * y * y 0.1 * x * y 0.2 * sqrt(abs(x)) ret (20.0 * sin(6.0 * x * .pi) 20.0 * sin(2.0 * x * .pi)) * 2.0 / 3.0 ret (20.0 * sin(y * .pi) 40.0 * sin(y / 3.0 * .pi)) * 2.0 / 3.0 ret (160.0 * sin(y / 12.0 * .pi) 320 * sin(y * .pi / 30.0)) * 2.0 / 3.0 return ret } private static func transformLon(_ x: Double, _ y: Double) - Double { var ret 300.0 x 2.0 * y 0.1 * x * x 0.1 * x * y 0.1 * sqrt(abs(x)) ret (20.0 * sin(6.0 * x * .pi) 20.0 * sin(2.0 * x * .pi)) * 2.0 / 3.0 ret (20.0 * sin(x * .pi) 40.0 * sin(x / 3.0 * .pi)) * 2.0 / 3.0 ret (150.0 * sin(x / 12.0 * .pi) 300.0 * sin(x / 30.0 * .pi)) * 2.0 / 3.0 return ret } }a和ee是地球椭球参数transformLat/transformLon是公开的偏移算法别去改里面的系数改了就对不上底图。开头的边界判断很重要国外坐标不做偏移否则你在境外用这个 Demo 会发现位置反而偏了。调用时机是定位回调里拿到latest.coordinate后先转再上地图逆地理编码时如果服务端要 WGS-84再写一个反向转换即可。3.3 地图展示与标注区域更新和自定义大头针地图这边核心是两件事把地图视野移到定位点以及画一个标注。MapViewController里的关键代码private let mapView MKMapView() private let locationManager LocationManager() override func viewDidLoad() { super.viewDidLoad() mapView.delegate self mapView.showsUserLocation true // 系统自带蓝点 view.addSubview(mapView) locationManager.onLocationUpdate { [weak self] location in let gcj CoordinateConverter.wgs84ToGcj02(location.coordinate) self?.updateMap(to: gcj) } locationManager.requestPermission() } private func updateMap(to coordinate: CLLocationCoordinate2D) { let region MKCoordinateRegion(center: coordinate, latitudinalMeters: 500, longitudinalMeters: 500) mapView.setRegion(region, animated: true) mapView.removeAnnotations(mapView.annotations.filter { $0 is MapAnnotation }) let annotation MapAnnotation() annotation.coordinate coordinate annotation.title 当前位置 mapView.addAnnotation(annotation) }showsUserLocation true会让系统自己画蓝点但那个蓝点用的是原始 WGS-84跟转换后的标注可能差一点Demo 里为了演示转换效果把系统蓝点保留、自定义标注用转换后坐标实际产品里二选一即可。latitudinalMeters设 500 表示视野纵向覆盖 500 米数值越小地图越“近”。每次更新前先移除旧标注再添加避免标注越堆越多——这是新手常犯的错跑一会儿地图上全是针。4. 跑起来与调试模拟器定位、真机差异和状态排查4.1 模拟器怎么模拟位置Xcode 模拟器默认没有真实定位得手动喂。运行起来后在模拟器菜单里选 Features → Location → Custom Location填一组经纬度比如 39.9087, 116.3975Demo 就会收到回调。也可以在 scheme 的 Options 里勾选 “Allow Location Simulation” 并指定一个 GPX 文件适合反复测试固定路线。注意模拟器给的坐标会被当成 WGS-84 处理转换逻辑照常走所以你能直观看到转换前后的偏移量。4.2 真机与模拟器的行为差异真机上第一次启动会弹权限框模拟器有时不弹或者直接给“允许”别被这个迷惑。真机定位首次回调可能延迟几秒didUpdateLocations可能连续来好几个点Demo 里取locations.last是最新点但如果你要做轨迹得把整个数组都处理。另外真机在室内精度会掉到几十米甚至上百米horizontalAccuracy 50的过滤会把点全丢掉表现就是“地图不动”——这时候把阈值放宽到 100 先验证链路通不通再收紧。4.3 状态排查定位不回调时看什么定位没反应按这个顺序查先看authorizationStatus是不是.notDetermined说明权限框没弹检查 Info.plist 描述再看是不是.denied去设置里手动开然后确认startUpdatingLocation真的被调了在locationManagerDidChangeAuthorization里打日志。如果权限正常还不回调检查是不是在模拟器里没设位置。最后看didFailWithError有没有被触发kCLErrorDenied是权限问题kCLErrorLocationUnknown通常是暂时拿不到等几秒会恢复。5. 避坑清单定位开发里最容易翻车的五个点5.1 现象地图上蓝点和标注差几百米 → 原因坐标系没转 → 解决统一走转换工具类这是最高频的问题。系统蓝点是 WGS-84国内底图是 GCJ-02不转就差几百米。解决方式是把所有要上地图的坐标都过一遍wgs84ToGcj02包括标注、区域中心、轨迹点。别只转标注忘了转setRegion的 center那样地图视野和标注会对不上。5.2 现象定位回调疯狂触发、手机发烫 → 原因distanceFilter 设成 0 且精度最高 → 解决按场景调参desiredAccuracy和distanceFilter是两个耗电大户。展示当前位置用kCLLocationAccuracyHundredMetersdistanceFilter 10足够导航类才需要 Best 小距离。Demo 默认值偏精度优先二次开发时第一件事就是按业务调这两个参数。5.3 现象权限框不弹直接进 denied → 原因Info.plist 缺描述或键名拼错 → 解决核对键名并清理安装NSLocationWhenInUseUsageDescription少一个字母都不行而且改完 Info.plist 要卸载重装系统会缓存旧的权限状态。模拟器上尤其明显删 App 重跑一次最稳。5.4 现象室内定位点乱跳 → 原因精度过滤太严或没做平滑 → 解决放宽阈值加简单滤波室内 GPS 信号差horizontalAccuracy经常上百米。除了放宽过滤阈值可以在didUpdateLocations里对连续几个点做加权平均或者用CLLocation的distance(from:)判断新点跟旧点距离是否合理跳太远的丢弃。Demo 只做了阈值过滤实际产品建议补一层平滑。5.5 现象后台收不到定位更新 → 原因没开 Background Modes 或没申请 Always 权限 → 解决补能力配置后台定位要同时满足Info.plist 有NSLocationAlwaysAndWhenInUseUsageDescription、Capabilities 勾了 Location updates、代码里调requestAlwaysAuthorization并设置allowsBackgroundLocationUpdates true。少一个都不行而且上架审核对后台定位用途查得严描述文案要写具体场景。6. 二次开发改造把 Demo 变成能用的定位模块拿到这个 Demo 之后我一般不会直接在上面堆业务而是先做三件事把它“产品化”。第一件是把LocationManager改成支持单次定位和持续定位两种模式——很多页面只需要拿一次当前位置用requestLocation()比startUpdatingLocation省电得多回调走didUpdateLocations但只来一次。第二件是给坐标转换加缓存和反向转换逆地理编码频繁调用时别每次都重算。第三件是把权限引导抽成独立流程用户拒绝后弹一个自定义提示引导去设置页而不是干等。改造时有个验证方法很实用写一个简单的日志面板把每次回调的原始坐标、转换后坐标、horizontalAccuracy、时间戳都打出来跑一段路对比轨迹是否平滑。我习惯在didUpdateLocations里加一个print开关调试期打开、上线关掉比事后猜“当时定位到底准不准”靠谱得多。还有一个具体技巧如果业务需要在地图上画轨迹别用MKPolyline每来一个点就重建一次点多了会卡。做法是维护一个坐标数组每隔 N 个点或者每 2 秒批量更新一次 overlay配合mapView.setVisibleMapRect自动缩放。这个改动不大但体验差别很明显。最后说个血泪教训早期我做定位模块时图省事把权限申请和定位启动写在viewDidLoad里结果用户从设置页改完权限回来页面已经销毁重建回调全丢了。从那以后我每次做定位相关页面都把权限状态监听放在viewWillAppear里重新检查一遍并且用locationManagerDidChangeAuthorization兜底确保权限变化后链路能自愈。希望这个 Demo 和这些踩坑记录能帮到你少走点弯路。本文还有配套的精品资源点击获取