joywayerandClaude Opus 4.7
323fb9074b
真机首次跑 ylgamehall 时 linker 报 7 个 Undefined symbol： - _CNCopyCurrentNetworkInfo / _CNCopySupportedInterfaces / _SCNetworkReachability* → SystemConfiguration.framework - _OBJC_CLASS_$_CTTelephonyNetworkInfo → CoreTelephony.framework - _OBJC_CLASS_$_EAAccessoryManager → ExternalAccessory.framework 根因：AMap 是 fat 静态库（`Vendor/AMap/*.framework`），它内部引用的系统 API 不会被自动带入 transitive 依赖，必须项目方手动 link。CocoaPods 时代由 podspec 自动声明（daoqi msext 走 Pods 故未在 pbxproj 显式 link ExternalAccessory）；本项目走 Vendor 手动接入路线，必须显式补齐。 工程：pbxproj 加 3 个 PBXBuildFile + PBXFileReference（Xcode UI 操作自动写入） 文档（永久记录避免重蹈）： - Vendor/AMap/README.md「工程接入步骤」第 5 步补齐 3 个系统 framework + 列出每个 framework 对应的 symbol - Vendor/AMap/README.md 末尾加「如果未来真机链接报 C++ symbol 缺失」 备用方案（加 libc++.tbd，daoqi 已加；当前 AMap 2.12.0 未触发） - docs/SDK-Integration-Guide.md §A.2 第 5 步同步 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# AMap 高德定位 SDK
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| AMapFoundationKit | 1.9.0+foundation.1b6fcf5 |
|
||
| AMapLocationKit | 2.12.0+loc.4f55976 |
|
||
| 来源 | [高德开放平台 iOS 定位 SDK 下载页](https://lbs.amap.com/api/ios-location-sdk/download) |
|
||
| 路径 | `Vendor/AMap/AMapFoundationKit.framework` / `Vendor/AMap/AMapLocationKit.framework` |
|
||
| 架构 | fat（x86_64 + **device** arm64）— **不含 simulator arm64**，详见下方「已知限制」 |
|
||
| 模块名 | `AMapFoundationKit` / `AMapLocationKit` |
|
||
| 引入日期 | 2026-06-22 |
|
||
|
||
## 工程接入步骤（用户在 Xcode 手动）
|
||
|
||
1. Project Navigator → 选中 ylgamehall target → General → Frameworks, Libraries, and Embedded Content
|
||
2. 点 `+` → Add Other → Add Files → 把 `Vendor/AMap/AMapFoundationKit.framework` 和 `AMapLocationKit.framework` 一起加入
|
||
3. 两个都设为 **Do Not Embed**（高德 fat `.framework` 是静态库，不能 Embed；Embed 会触发链接器对 `__OBJC` 段重复符号错误）
|
||
4. Build Settings → Framework Search Paths 自动会被 Xcode 写入 `$(PROJECT_DIR)/Vendor/AMap`
|
||
5. **必须额外 link 3 个系统 framework**（关键！否则真机链接器报 Undefined symbol，模拟器可能不报）：
|
||
- **SystemConfiguration.framework** ← `_CNCopyCurrentNetworkInfo` / `_SCNetworkReachability*`
|
||
- **CoreTelephony.framework** ← `_OBJC_CLASS_$_CTTelephonyNetworkInfo`
|
||
- **ExternalAccessory.framework** ← `_OBJC_CLASS_$_EAAccessoryManager`
|
||
|
||
操作：同样 `+` → 搜索框输入 framework 名 → Add（Embed = Do Not Embed）。
|
||
|
||
原因：AMap 是静态库（fat .framework），它内部引用的系统 API 不会被自动带入 transitive 依赖，必须项目方手动 link。CocoaPods 时代由 podspec 自动声明这些依赖（daoqi msext 走 Pods 故未在 pbxproj 显式 link ExternalAccessory），但本项目走 Vendor 手动接入路线，必须显式补齐。
|
||
|
||
6. Clean Build Folder 后 BuildProject
|
||
|
||
接入完毕后，源码内 `#if canImport(AMapLocationKit)` 守卫将激活真实路径。
|
||
|
||
## 如果未来真机链接报 C++ symbol 缺失（`std::__1::*`）
|
||
|
||
加 **libc++.tbd**（同样 `+` 搜索）— 高德 SDK 内部含 C++ 代码，部分版本需要显式 link 系统 C++ 库。daoqi msext 已显式 link `libc++.tbd` + `libc++.1.tbd`；当前 ylgamehall 在 2.12.0 上未触发，先不加；触发再补。
|
||
|
||
## 已知限制：M 芯片 Mac 模拟器无法链接
|
||
|
||
**症状**：M Mac + iOS-simulator target 链接报 `Building for 'iOS-simulator', but linking in object file (... AMapLocationKit[arm64]) built for 'iOS'`。
|
||
|
||
**根因**：
|
||
- 高德官方至今**不提供 xcframework**（2026-06 确认），只发布传统 fat `.framework`
|
||
- fat library 内的 arm64 是 **device** arm64，不是 simulator arm64
|
||
- M 芯片模拟器需要 **simulator** arm64 slice，fat 库给不了
|
||
|
||
**项目决策（2026-06-23）**：**接受模拟器失败，开发期跑真机**，与 daoqi msext 维护实践一致（daoqi 同款 fat framework，CocoaPods 也未设 EXCLUDED_ARCHS，多年来一直靠真机维护）。理由：
|
||
- 本项目企业签 / 超级签分发，**真机才是真实使用环境**，模拟器价值有限
|
||
- daoqi msext 同款配置上线多年稳定，证明真机路径已被验证
|
||
- 配 `EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64` 走 Rosetta x86_64 模拟器虽然可行，但：
|
||
- 需要安装 iOS 18 及之前的 simulator runtime（含 x86_64，iOS 26 runtime 已 arm64-only）
|
||
- Rosetta 模拟器迭代慢
|
||
- 增加 Build Settings 维护负担
|
||
- 若未来高德发布 xcframework，无缝切换（直接替换 `Vendor/AMap/*.xcframework` + 同步本 README）
|
||
|
||
**不要做的事**：
|
||
- ❌ 不要尝试自造 xcframework 把 fat 拆开（顶多含 `ios-arm64` + `ios-x86_64-simulator`，M Mac 仍需 Rosetta，等效于设 EXCLUDED_ARCHS，徒增工程复杂度）
|
||
- ❌ 不要为了过模拟器 build 而修改 `EXCLUDED_ARCHS` —— 真机分发不需要，且会让真机 Debug 默认排除掉 arm64
|
||
- ❌ 不要切换到 CocoaPods 拉 AMap pod —— 违反 daoqi `CLAUDE.md` ADR-006
|
||
|
||
**何时重新评估**：高德发布 xcframework 的那一天。
|
||
|
||
## 凭证
|
||
|
||
参 `docs/SDK-Integration-Guide.md §0` 凭证总表。APIKey 沿用 msext（`b0d4a8e3fcbbcc0dd96283b7df6a4494`，与 Bundle ID `com.skyapp.ylgamehall` 绑死）。
|
||
|
||
## Info.plist 必需
|
||
|
||
- `NSLocationWhenInUseUsageDescription`：定位权限文案（已由工程接入时统一添加，见 SDK-Integration-Guide §2.2）
|