修复 AMap 真机链接错:补 3 个系统 framework + 永久文档化

真机首次跑 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>
This commit is contained in:
joywayer
2026-06-23 02:50:29 +08:00
co-authored by Claude Opus 4.7
parent e6bcb32820
commit 323fb9074b
3 changed files with 33 additions and 2 deletions
+14 -1
View File
@@ -16,10 +16,23 @@
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. Clean Build Folder 后 BuildProject
5. **必须额外 link 3 个系统 framework**(关键!否则真机链接器报 Undefined symbol,模拟器可能不报):
- **SystemConfiguration.framework** ← `_CNCopyCurrentNetworkInfo` / `_SCNetworkReachability*`
- **CoreTelephony.framework** ← `_OBJC_CLASS_$_CTTelephonyNetworkInfo`
- **ExternalAccessory.framework** ← `_OBJC_CLASS_$_EAAccessoryManager`
操作:同样 `+` → 搜索框输入 framework 名 → AddEmbed = 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'`