集成Google Maps SDK的XCFramework在iOS应用中地图不显示求助

问题概述 #

自定义iOS Framework项目通过CocoaPods引入GoogleMaps iOS SDK（v8.4.0/v9.1.0），打包为XCFramework后，其他iOS App引入该库时，打开包含GMSMapView的视图控制器出现以下问题：

• 地图无内容显示（已配置API密钥）
• 控制台持续报错：[GMSx_SRLRegistry internalService:scopeTags:]: No binding was found for required, single-bound service: GMSAnalyticsLogging_API

环境信息：

• IDE：Xcode 16.0
• XCFramework项目Swift版本：5.0
• CocoaPods版本：1.15.2
• 运行系统：iOS 17.7（iPhone 15）/iOS 18.0（iPhone 16模拟器）

错误本质 #

该错误源于GoogleMaps SDK的内部服务注册机制失效，核心是打包XCFramework过程中，SDK的依赖组件、资源或动态库关联被破坏，导致GMSAnalyticsLogging_API这类核心服务无法完成绑定。

可能的操作失误及修复步骤 #

1. 打包时未包含GoogleMaps的全部依赖动态库 #

GoogleMaps SDK包含多个关联动态库（如GoogleMapsCore.framework、GoogleMapsBase.framework、GoogleMapsAnalytics.framework等），若自定义Framework仅打包自身代码，未处理这些依赖，会导致SDK服务无法初始化。

修复：

• 确认自定义Framework的Podfile中正确引入GoogleMaps，执行pod install后，Pods目录下的GoogleMaps相关组件完整
• 采用动态依赖方式：让宿主App通过自身Podfile直接引入GoogleMaps SDK，而非将其打包进自定义XCFramework；或打包XCFramework时，将所有GoogleMaps依赖动态库一并包含，并在XCFramework的Info.plist中声明依赖。

2. 强制将GoogleMaps打包为静态库 #

GoogleMaps v8.x+版本依赖动态库的服务注册逻辑，若自定义Framework强制将其打包为静态库，会破坏内部服务绑定机制。

修复：

• 在自定义Framework的Podfile中明确指定GoogleMaps为动态库：

  pod 'GoogleMaps', '~> 8.4.0', :linkage => :dynamic, :modular_headers => true
  

• 重新执行pod install后，重新打包XCFramework。

3. 丢失GoogleMaps的资源文件 #

GoogleMaps SDK依赖GoogleMaps.bundle中的资源（地图样式、本地化文件等），打包时未包含该资源会导致服务初始化失败。

修复：

• 打包XCFramework时，将GoogleMaps.bundle添加到Framework的资源目录中；或让宿主App单独引入该bundle（可通过CocoaPods自动获取）。

4. 宿主App未正确初始化SDK #

即使自定义Framework中配置了API密钥，宿主App需确保初始化逻辑在GMSMapView创建前执行。

修复：

• 在宿主App的AppDelegate或SceneDelegate的启动方法中，调用：

  GMSServices.provideAPIKey("YOUR_API_KEY")
  

• 确保该代码在任何GMSMapView实例化之前执行。

5. Xcode 16打包机制兼容性问题 #

Xcode 16对XCFramework打包的规则有更新，可能导致依赖关联失效。

修复：

• 使用命令行工具打包XCFramework，明确指定构建参数：

  # 归档iOS真机版本
  xcodebuild archive -scheme YourFramework -destination "generic/platform=iOS" -archivePath ./build/ios.xcarchive SKIP_INSTALL=NO BUILD_LIBRARY_FOR_DISTRIBUTION=YES
  # 归档iOS模拟器版本
  xcodebuild archive -scheme YourFramework -destination "generic/platform=iOS Simulator" -archivePath ./build/iossim.xcarchive SKIP_INSTALL=NO BUILD_LIBRARY_FOR_DISTRIBUTION=YES
  # 创建XCFramework
  xcodebuild -create-xcframework -framework ./build/ios.xcarchive/Products/Library/Frameworks/YourFramework.framework -framework ./build/iossim.xcarchive/Products/Library/Frameworks/YourFramework.framework -output ./build/YourFramework.xcframework
  

• 打包完成后，检查XCFramework的内部结构，确保GoogleMaps的依赖框架被正确关联。

验证流程 #

1. 按上述步骤修复后重新打包自定义XCFramework
2. 在宿主App中引入XCFramework，并确保宿主App的Podfile中正确引入GoogleMaps（若采用动态依赖方式）
3. 确认宿主App的API密钥初始化逻辑正确
4. 运行App，检查控制台错误是否消失，地图是否正常加载

内容的提问来源于stack exchange，提问作者Xattacker Tao