如何将带依赖的二进制框架从CocoaPods迁移至SPM或XCFramework？

问题本质 #

你当前构建的XCFramework仅包含自身代码，未将CocoaPods依赖静态链接进去；同时SPM引入源码仓库时的"No such module"错误，是因为你的Framework模块信息未声明依赖，且CocoaPods与SPM的依赖管理链不兼容导致的。

方案1：构建自包含的XCFramework（纯二进制分发） #

将所有依赖静态链接到你的Framework中，生成无需额外依赖的XCFramework：

• 调整CocoaPods配置为静态链接
  修改Podfile，确保所有依赖以静态库形式引入：

  # 全局设置所有pod为静态链接
  use_frameworks! :linkage => :static
  
  target 'MyFramework' do
    pod 'CocoaLumberjack'
    pod 'KeychainAccess'
    pod 'RealmSwift'
    pod 'ZIPFoundation'
  end
  

  执行pod install更新配置。

• 检查Framework的Build Settings
  打开你的Framework target的Build Settings：

  • 确保Mach-O Type设为Static Library
  • Build Library for Distribution保持YES
  • Skip Install保持NO
  • Other Linker Flags添加-ObjC（处理依赖中的Category代码）

• 重新构建XCFramework
  执行你原有的构建命令（确保archives目录已创建）：

  # 归档模拟器版本
  xcodebuild archive \
  -scheme MyFramework \
  -destination "generic/platform=iOS Simulator" \
  -archivePath "archives/ios_simulator.xcarchive" \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
  SKIP_INSTALL=NO \
  -workspace MyFramework.xcworkspace
  
  # 归档真机版本
  xcodebuild archive \
  -scheme MyFramework \
  -destination "generic/platform=iOS" \
  -archivePath "archives/ios_devices.xcarchive" \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
  SKIP_INSTALL=NO \
  -workspace MyFramework.xcworkspace
  
  # 生成XCFramework
  xcodebuild \
  -create-xcframework \
  -framework ./archives/ios_devices.xcarchive/Products/Library/Frameworks/MyFramework.framework \
  -framework ./archives/ios_simulator.xcarchive/Products/Library/Frameworks/MyFramework.framework \
  -output ./archives/MyFramework.xcframework
  

  此时生成的XCFramework已包含所有依赖代码，导入项目后无需额外添加依赖。

方案2：通过SPM分发（源码/二进制） #

如果需要支持SPM分发，需在Package.swift中声明依赖，让Xcode自动管理依赖链：

• 迁移依赖管理到SPM（推荐）
  彻底移除CocoaPods，改用SPM管理依赖：

  1. 删除项目中的Podfile、Podfile.lock、MyFramework.xcworkspace，保留MyFramework.xcodeproj
  2. 打开xcodeproj，通过File > Add Packages...添加以下依赖（指定对应版本）：
     • CocoaLumberjack
     • KeychainAccess
     • RealmSwift
     • ZIPFoundation
  3. 在Framework target的General > Frameworks, Libraries, and Embedded Content中，将这些依赖设为Do Not Embed

• 创建Package.swift配置
  若为源码分发，创建如下配置：

  // swift-tools-version: 5.9
  import PackageDescription
  
  let package = Package(
      name: "MyFramework",
      platforms: [.iOS(.v14)], // 根据你的最低版本调整
      products: [
          .library(name: "MyFramework", targets: ["MyFramework"])
      ],
      dependencies: [
          .package(url: "https://github.com/CocoaLumberjack/CocoaLumberjack.git", from: "3.8.0"),
          .package(url: "https://github.com/kishikawakatsumi/KeychainAccess.git", from: "4.2.2"),
          .package(url: "https://github.com/realm/realm-swift.git", from: "10.35.0"),
          .package(url: "https://github.com/weichsel/ZIPFoundation.git", from: "0.9.16")
      ],
      targets: [
          .target(
              name: "MyFramework",
              dependencies: [
                  .product(name: "CocoaLumberjack", package: "CocoaLumberjack"),
                  .product(name: "KeychainAccess", package: "KeychainAccess"),
                  .product(name: "RealmSwift", package: "realm-swift"),
                  .product(name: "ZIPFoundation", package: "ZIPFoundation")
              ],
              path: "path/to/your/framework/source/files" // 指向你的Framework源码目录
          )
      ]
  )
  

  若为二进制SPM分发，将target改为binaryTarget：

  .binaryTarget(
      name: "MyFramework",
      path: "./MyFramework.xcframework"
  )
  

  同时保留第三方依赖声明，Xcode会自动下载并链接依赖。

解决"No such module"错误的关键 #

• 禁止混用CocoaPods和SPM，必须统一依赖管理方式（全CocoaPods或全SPM）
• 迁移到SPM后，Xcode会自动生成包含依赖引用的模块文件（.modulemap或.swiftmodule）
• RealmSwift需额外注意：迁移后要确保Build Phases中的Realm相关脚本（如数据库迁移脚本）配置正确

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