解决 CocoaPods OpenSSL 版本冲突的 Pod 安装问题

2024-12-29 21:06:59

解决 OpenSSL 版本冲突的 Pod 安装问题

当项目中依赖的多个 Pod 使用了不同版本的 OpenSSL 时，会遇到命名冲突导致的安装或运行时错误。尤其是在使用了 openssl.xcframework 和 OpenSSL.xcframework 这两个名称略有差异的 framework 时，这种问题更加常见。本篇文章将探讨这一问题产生的原因，并提供有效的解决方案。

问题根源

核心问题在于，虽然两个 Pod 都依赖 OpenSSL，但是他们使用的 OpenSSL 版本（以及 framework 名称）不同。CocoaPods 在链接依赖时，默认会将所有 framework 放到同一个命名空间中。这导致当两个 framework 使用冲突的名称（例如，虽然都是 OpenSSL，但是文件名为 openssl.xcframework 和 OpenSSL.xcframework）时， CocoaPods 就会抛出冲突错误。

即使尝试通过子项目分离，或者手动添加其中一个 framework 来规避 CocoaPods 的检查，也无法从根本上解决问题，因为在运行时只会加载其中一个 OpenSSL，这会导致代码中 import 了另一个版本的 Pod 运行时崩溃。这种运行时崩溃的原因在于 OpenSSL 和 openssl 的符号冲突。

解决方案

有几种方法可以解决这一冲突：

1. 强制 Pod 使用相同的 OpenSSL 版本

原理: 这是最直接的方法。通过修改 Podfile 强制所有依赖 OpenSSL 的 Pod 使用相同版本。
操作步骤:
1. 检查 Pods 的 podspec 文件，找到依赖的 OpenSSL 版本。通常，可以在依赖关系或直接的 framework 定义中找到版本信息。
2. 在 Podfile 中指定全局的 OpenSSL 版本。例如，假设需要统一使用 1.1.1 版：

  # 如果已知 Pod 具体版本则可以指定具体版本
  pod 'OpenSSL-Universal', '~> 1.1.1'  #  替换为所需的Pod 名称及版本

  # 如果只需要其中某一个Pod指定了openssl 版本
  # 或者OpenSSL 是这个 pod 里面的 subpod 依赖

  pod 'CGModule' , :subspecs => ['default'], :dependencies=> {
        'OpenSSL-Universal'=> '1.1.1'  # 将子 Pod 版本锁定
    }

运行 pod install 。如果所有 Pod 都可以兼容这一版本，问题应该就可以解决。如果不能兼容则会出现错误，提示升级或者降级Pod 。

注意事项:
这需要在安装依赖前就清楚每一个 Pod 所使用的 openssl 版本，且各个版本相互兼容。
需要测试确保统一版本不会影响项目原有功能。

2. 使用 installer hook 修改 framework 的名称

原理: 通过 Pod 的 hook 功能在安装阶段修改其中一个 framework 的名称，来避免名称冲突。这种方法需要对 Ruby 和 CocoaPods 的 hook 有一定了解。
操作步骤:
1. 在 Podfile 中添加以下代码：

post_install do |installer|
  installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['OTHER_LDFLAGS'] = [
             '$(inherited)',
             '-framework',
             'openssl', # 统一删除此lib
           ]
      end
    end

  installer.pods_project.targets.each do |target|
        if target.name == 'CGModule' # 指定特定pod 避免修改所有framework

            target.build_configurations.each do |config|
             config.build_settings['OTHER_LDFLAGS'] = [
                  '$(inherited)',
                 '-framework',
                   'OpenSSL'  # 如果是静态库 则删除 替换为对应的dylib lib文件名称
              ]

              config.build_settings['FRAMEWORK_SEARCH_PATHS'] << '$(PODS_ROOT)/CGModule/lib'
          end

           target.add_file_references_for_group_with_path('lib/OpenSSL.framework'  , 'Frameworks') # 如果是静态库 添加对应dylib或者lib
        end
    end
end

2.运行pod install。
3. 修改项目本身代码,确保使用的是新加入的OpenSSL。

注意事项:
openssl.framework 名称将被修改为 OpenSSL.framework
确保所有地方的代码引用的也是 OpenSSL。

3. 隔离依赖库（通过 Subspec 或 Package Manager）

原理： 对于复杂的项目或模块化程度较高的项目，可以将这些具有依赖冲突的模块放入单独的子项目或者使用例如 Swift Package Manager (SPM) 的外部工具来管理。这样做可以更清晰的分割依赖关系，隔离框架，并避免 Cocoapods 本身的框架冲突。
操作步骤:
1. 创建一个新的 XCode Project 或 workspace，并把它视为原项目的子模块或者独立 Package。
2. 将 CGModule 的依赖库直接嵌入这个新建的子项目/Package中。注意避免直接 import 其他 project 或workspace 的 framework，要确保 framework 只在该隔离的子模块中工作。
3. 将隔离后的项目/package 添加到你的原项目。在原有主项目中可以不适用 CocoaPods 的方式来管理隔离后的依赖。可以使用 subproject 添加依赖，或是使用 swift package manager 管理该package 的方式引入依赖。
4. 测试，并解决由于依赖引用更改导致的代码冲突。
注意事项:
- 对于大型项目，使用 Subspec 或 Package Manager 可能意味着架构的大规模调整，请谨慎选择。