axiom-location

位置与地图

对于任何位置服务、地图、地理围栏或 Core Location / MapKit 工作，都必须使用此技能。

快速参考

症状 / 任务	参考
授权策略（使用期间与始终）	参见 skills/core-location.md
监测方式（持续、重大变化、CLMonitor）	参见 skills/core-location.md
精度选择、后台位置	参见 skills/core-location.md
CLLocationUpdate、CLMonitor、CLServiceSession API	参见 skills/core-location-ref.md
授权 API 模式、地理围栏 API	参见 skills/core-location-ref.md
罗盘航向、航向参考体（headingBody）	参见 skills/core-location-ref.md（第 12 部分）
始终收不到位置更新	参见 skills/core-location-diag.md
后台位置功能停止工作	参见 skills/core-location-diag.md
授权始终被拒绝、地理围栏失败	参见 skills/core-location-diag.md
SwiftUI Map、注释、标记、聚类	参见 skills/mapkit.md
选择 MKMapView 还是 SwiftUI Map	参见 skills/mapkit.md
搜索、路线、路径规划	参见 skills/mapkit.md
MapKit API：Marker、Annotation、MKLocalSearch、MKDirections	参见 skills/mapkit-ref.md
Look Around、MKMapSnapshotter、MKMapItem	参见 skills/mapkit-ref.md
注释未显示、区域跳动	参见 skills/mapkit-diag.md
聚类无法工作、搜索失败	参见 skills/mapkit-diag.md
覆盖层渲染、用户位置未显示	参见 skills/mapkit-diag.md

决策树

digraph location {
    start [label="Location / Maps task" shape=ellipse];
    domain [label="Core Location or MapKit?" shape=diamond];
    cl_type [label="Need what?" shape=diamond];
    mk_type [label="Need what?" shape=diamond];

    start -> domain;

    domain -> cl_type [label="Core Location"];
    domain -> mk_type [label="MapKit / Maps"];

    cl_type -> "skills/core-location.md" [label="authorization, monitoring\nstrategy, accuracy,\nbackground location"];
    cl_type -> "skills/core-location-ref.md" [label="API syntax\n(CLLocationUpdate,\nCLMonitor, CLServiceSession)"];
    cl_type -> "skills/core-location-diag.md" [label="something broken\n(no updates, denied,\ngeofence not firing)"];

    mk_type -> "skills/mapkit.md" [label="patterns, decisions\n(SwiftUI Map vs MKMapView,\nannotations, search)"];
    mk_type -> "skills/mapkit-ref.md" [label="API syntax\n(Marker, Annotation,\nMKLocalSearch, MKDirections)"];
    mk_type -> "skills/mapkit-diag.md" [label="something broken\n(annotations missing,\nregion jumping, clustering)"];
}

1. 授权策略、监测方式、精度？→ skills/core-location.md 1a. 需要特定 API 语法（CLLocationUpdate、CLMonitor、CLServiceSession）？→ skills/core-location-ref.md 1b. 位置功能无法正常工作？→ skills/core-location-diag.md
2. 添加地图、注释、搜索、路线？→ skills/mapkit.md 2a. 需要特定 MapKit API 语法（Marker、MKLocalSearch、MKDirections）？→ skills/mapkit-ref.md 2b. 地图显示异常？→ skills/mapkit-diag.md
3. 位置功能耗电？→ 参见 axiom-performance（skills/energy.md）
4. 位置相关的后台任务调度？→ 参见 axiom-integration
5. 位置相关的隐私清单？→ 参见 axiom-integration

冲突解决

location 与 axiom-performance：位置功能耗电时：

1. 先尝试 location——精度过高或持续更新是首要原因。skills/core-location.md 介绍了精度选择和监测策略。
2. 仅当位置设置已正确时才使用 axiom-performance——排除明显的过度跟踪后再进行性能分析。

location 与 axiom-integration：实现后台位置功能时：

• 后台位置配置（Info.plist、功能、CLServiceSession）→ 使用 location
• 使用 BGTaskScheduler 定期处理位置 → 使用 axiom-integration

location 与 axiom-data：存储或同步位置数据时：

• 获取位置更新、地理围栏 → 使用 location
• 持久化位置历史记录、CloudKit 同步 → 使用 axiom-data

location 与 axiom-build：模拟器中的位置权限失败时：

• 授权对话框、Info.plist 键 → 使用 location（skills/core-location-diag.md）
• 模拟器 GPS 模拟、simctl location → 使用 axiom-build

关键模式

Core Location 核心定位（skills/core-location.md）：

• 权限升级策略（先请求使用 App 期间，再请求始终允许）
• 监控决策树（持续监控与重大变化监控和 CLMonitor）
• 精度选择及其对电池的影响
• 后台定位配置
• 反模式及其时间成本（过早请求始终允许权限、不必要的持续更新）

Core Location API 核心定位 API（skills/core-location-ref.md）：

• CLLocationUpdate AsyncSequence（iOS 17+）
• 基于条件的 CLMonitor 地理围栏（iOS 17+）
• 声明式授权 CLServiceSession（iOS 18+）
• 授权 API 模式、后台模式配置

Core Location 诊断（skills/core-location-diag.md）：

• 始终收不到位置更新
• 后台定位停止工作
• 授权始终被拒绝
• 地理围栏事件未触发
• 定位精度出乎意料地差

MapKit（skills/mapkit.md）：

• SwiftUI Map 与 MKMapView 的决策树
• 注记模式（Marker、自定义 Annotation）
• 搜索（MKLocalSearch、自动补全）
• 路线和路径规划
• 反模式（在视图主体中添加注记、不复用视图、setRegion 循环）

MapKit API（skills/mapkit-ref.md）：

• SwiftUI Map API（MapCameraPosition、内容构建器、控件）
• MKMapView 委托模式
• MKLocalSearch、MKDirections
• Look Around、MKMapSnapshotter
• 聚类配置

MapKit 诊断（skills/mapkit-diag.md）：

• 注记未显示（纬度/经度颠倒、缺少委托）
• 地图区域跳动/循环（updateUIView 防护）
• 聚类不起作用（缺少 clusteringIdentifier）
• 搜索无结果（resultTypes、区域偏置）
• 覆盖层渲染失败

避免自我合理化

想法	事实
“直接一开始就请求始终允许权限”	拒绝率为 30-60%。先请求使用 App 期间的权限，之后再升级。skills/core-location.md 介绍了相关策略。
“我的使用场景适合持续更新”	即使 App 不需要亚秒级定位，持续更新也会耗尽电量。请使用重大变化监控或 CLMonitor。
“我会用 MKMapView，它更灵活”	自 iOS 17 起，SwiftUI Map 已能满足大多数使用场景。MKMapView 意味着需要编写 UIViewRepresentable 样板代码。skills/mapkit.md 提供了决策树。
“少量注记放在视图主体里没问题”	每次视图更新都会重新创建注记。即使只有 50 项也会造成卡顿。请将其移到模型中，并使用 @State 或 @Observable。
“我知道地理围栏的工作原理”	CLMonitor（iOS 17+）通过条件取代了旧版区域监控。API 已发生重大变化。
“后台定位只需要开启功能”	除了 Info.plist 键和功能外，还需要 CLServiceSession（iOS 18+）以及正确的授权级别。缺少任何一项都会导致功能静默失效。
“我之后再处理定位错误”	授权被拒绝不是错误，而是默认状态。从一开始就要处理这种情况。

示例调用

用户：“如何请求定位权限？” → 阅读：skills/core-location.md

用户：“CLLocationUpdate API 是什么？” → 阅读：skills/core-location-ref.md

用户：“我始终收不到位置更新。” → 阅读：skills/core-location-diag.md

用户：“如何添加带图钉的地图？” → 阅读：skills/mapkit.md

用户：“SwiftUI Map API 是什么？” → 阅读：skills/mapkit-ref.md

用户：“我的注记没有显示在地图上。” → 阅读：skills/mapkit-diag.md

用户：“如何实现地理围栏？” → 阅读：先看 skills/core-location.md，再看 skills/core-location-ref.md

用户：“定位很耗电。” → 阅读：skills/core-location.md，然后参阅 axiom-performance（skills/energy.md）

用户：“如何为地图添加搜索功能？” → 阅读：先看 skills/mapkit.md，再看 skills/mapkit-ref.md