joywayerandClaude Opus 4.7
01780704cd
高德官方至今不提供 xcframework，只发布 fat .framework（含 x86_64 + device arm64）。M 芯片 Mac iOS-simulator target 链接失败是 fat 库的物理限制，与 daoqi msext 维护实践一致——开发期跑真机即可。 不动 Build Settings、不自造 xcframework、不切 CocoaPods 三条「不要做」也 一并明示，避免未来维护者花时间在这条死路上： - Vendor/AMap/README.md 新增「已知限制」章节，含决策原因 + 三条「不要做」 - docs/SDK-Integration-Guide.md §A.2 简明提示 + 链回 README Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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 手动）
- Project Navigator → 选中 ylgamehall target → General → Frameworks, Libraries, and Embedded Content
- 点
+→ Add Other → Add Files → 把Vendor/AMap/AMapFoundationKit.framework和AMapLocationKit.framework一起加入 - 两个都设为 Do Not Embed（高德 fat
.framework是静态库，不能 Embed；Embed 会触发链接器对__OBJC段重复符号错误） - Build Settings → Framework Search Paths 自动会被 Xcode 写入
$(PROJECT_DIR)/Vendor/AMap - Clean Build Folder 后 BuildProject
接入完毕后，源码内 #if canImport(AMapLocationKit) 守卫将激活真实路径。
已知限制：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.mdADR-006
何时重新评估：高德发布 xcframework 的那一天。
凭证
参 docs/SDK-Integration-Guide.md §0 凭证总表。APIKey 沿用 msext（b0d4a8e3fcbbcc0dd96283b7df6a4494，与 Bundle ID com.skyapp.ylgamehall 绑死）。
Info.plist 必需
NSLocationWhenInUseUsageDescription：定位权限文案（已由工程接入时统一添加，见 SDK-Integration-Guide §2.2）