daoqi/youle_app_ios_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
youle_app_ios_v2/Vendor/AMap
T
History
joywayerandClaude Opus 4.7 323fb9074b 修复 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>
2026-06-23 02:50:29 +08:00
..
AMapFoundationKit.framework
Phase 4.E + Phase 5 + Phase 3.C 七牛上传：代码侧 SDK 接入（SPM 优先 / Vendor 兜底）
2026-06-22 22:22:23 +08:00
AMapLocationKit.framework
Phase 4.E + Phase 5 + Phase 3.C 七牛上传：代码侧 SDK 接入（SPM 优先 / Vendor 兜底）
2026-06-22 22:22:23 +08:00
README.md
修复 AMap 真机链接错：补 3 个系统 framework + 永久文档化
2026-06-23 02:50:29 +08:00

README.md

AMap 高德定位 SDK

项 值
AMapFoundationKit 1.9.0+foundation.1b6fcf5
AMapLocationKit 2.12.0+loc.4f55976
来源 高德开放平台 iOS 定位 SDK 下载页
路径 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）
Reference in New Issue View Git Blame Copy Permalink