pod-binary-pack 1.0.0

data/lib/core/repo_xcode_package.rb

@@ -0,0 +1,713 @@
+# frozen_string_literal: true
+require 'yaml'
+require 'json'
+require 'tempfile'
+require 'shellwords'
+require_relative 'repo_xcode'
+require_relative 'repo_module_source'
+require_relative 'build_item'
+require_relative 'util/file_helper'
+require_relative 'hook_manager'
+
+module Build
+  class RepoXcodePackage < RepoXCode
+
+    # cocoapods-yaml 插件的依赖文件命名
+    LOCAL_DEPENDENCIES_FILE = 'LocalDependencies.yaml'
+    TARGET_DEPENDENCIES_GLOB = '*Dependencies.yaml'
+
+    # 当前编译模式
+    attr_accessor :debug_mode
+
+    # 真机产物路径 在编译完成前产物为空
+    attr_accessor :real_device_archive_path
+
+    # 模拟器产物路径 在编译完成前产物为空
+    attr_accessor :simulator_archive_path
+
+    # @return [Array] resource_bundles的路径(在编译完成前为空)
+    attr_accessor :resource_bundles_paths
+    # @return [Array] resource的路径(在编译完成前为空)
+    attr_accessor :resource_paths
+
+    def initialize(path, ssh_url, branch, xcworkspace, scheme, **signing_options)
+      super(path, ssh_url, branch, xcworkspace, scheme, **signing_options)
+      @debug_mode = false
+      @resource_bundles_paths = Array.new
+      @resource_paths = Array.new
+    end
+
+    # 打包前准备工程内的 pod yaml 文件
+    # 打包工程即壳工程本身，<Target>Dependencies.yaml 已在工程内，
+    # 这里只保留扩展点(如三方库特殊替换)
+    def prepare_yaml_files
+      hooker = HookManager.instance
+      hooker.trigger_hook(Status::XCODE_PACKAGE_COPY_YAML, self.path)
+    end
+
+    # 打包期临时桩化 main.m 后执行块，结束后必定还原。
+    #
+    # 背景: TRIM_UNUSED_POD 裁剪时 cocoapods-yaml 会扫描壳工程自有源码的 #import <组件/...>
+    # 来决定保留哪些 pod；而壳工程 main.m 引用了 BSLaunch 等业务组件。
+    # 为让裁剪只安装目标组件(及其依赖)并保证 archive 编译通过，
+    # pod update 前把 main.m 替换为仅依赖 UIKit 的最小 AppDelegate(同旧打包工程的做法)。
+    def with_build_stub
+      stub_main_m
+      yield
+    ensure
+      restore_main_m
+    end
+
+    # 生成本地依赖覆盖文件(打包期临时文件，结束后删除，不提交)
+    def generate_local_yaml(repo_module_source)
+      local_yaml_path = File.join(self.path, LOCAL_DEPENDENCIES_FILE)
+      pod_name = repo_module_source.pod_name
+
+      dependencies_content = {}
+      dependencies_content["TRIM_UNUSED_POD"] = true
+      dependencies_content["PODS"] = []
+
+      # 先从壳工程 target 依赖文件里找配置(subspecs/configurations)，找不到则生成最小条目
+      pod_items = get_pod_in_self(pod_name)
+      if pod_items.any?
+        # 优先root声明(携带subspecs/configurations)，cocoapods-yaml合并时按root覆盖
+        root_item = pod_items.find { |item| item["pod"] == pod_name } || pod_items.first
+        dependency = create_local_yaml_pod(pod_name, repo_module_source)
+
+        # 多subspec组件整包全量构建：以podspec中声明的全部subspec为准(保证每个模块自身的
+        # 三方依赖在archive时都存在)，不再只取壳工程声明的子集；无subspec时沿用壳工程配置。
+        # 互斥subspec组件(如FMDB的standard/standalone/SQLCipher是不同sqlite后端，全量合并
+        # 编译必冲突)可通过 build.yml components.<组件>.subspecs 显式指定集成集合
+        explicit_subspecs = repo_module_source.respond_to?(:build_subspecs) ? repo_module_source.build_subspecs : nil
+        build_subspecs = repo_module_source.respond_to?(:resolved_build_subspecs) ? repo_module_source.resolved_build_subspecs : []
+        if build_subspecs.any?
+          dependency["subspecs"] = build_subspecs
+          if explicit_subspecs
+            Build.log.detail("组件#{pod_name}按配置集成#{build_subspecs.size}个subspec: #{build_subspecs.join('、')}")
+          else
+            Build.log.detail("组件#{pod_name}含#{build_subspecs.size}个subspec，打包集成全部: #{build_subspecs.join('、')}")
+          end
+        elsif root_item["subspecs"]
+          dependency["subspecs"] = root_item["subspecs"]
+        end
+        dependency["configurations"] = root_item["configurations"] if root_item["configurations"]
+        dependencies_content["PODS"] << dependency
+
+        # 更新下编译模式
+        __update_debug_mode(root_item)
+      else
+        dependencies_content["PODS"] << create_local_yaml_pod(pod_name, repo_module_source)
+      end
+
+      File.open(local_yaml_path, 'w') { |file|
+        file.write(dependencies_content.to_yaml)
+      }
+
+    end
+
+    # 壳工程所有 target 依赖文件的绝对路径(排除本地覆盖文件)
+    def target_dependency_paths
+      Dir.glob(File.join(self.path, TARGET_DEPENDENCIES_GLOB))
+         .reject { |p| File.basename(p) == LOCAL_DEPENDENCIES_FILE }
+         .sort
+    end
+
+    # 从所有 target 依赖文件中读取某个pod的声明(root或subspec)
+    def get_pod_in_self(pod_name)
+      target_dependency_paths.each do |yaml_path|
+        result = get_pod_in_yaml(pod_name, yaml_path)
+        return result if result.any?
+      end
+      []
+    end
+
+    def get_pod_in_yaml(pod_name, yaml_path)
+      result = []
+
+      # 壳工程未提供该文件时视为无配置，由调用方走默认生成分支
+      return result unless File.exist?(yaml_path)
+
+      yaml_content = load_dependency_yaml(yaml_path)
+      pods_array = (yaml_content.is_a?(Hash) && yaml_content["PODS"]) ? yaml_content["PODS"] : []
+
+      pods_array.each { |item|
+        next unless item["pod"]
+        if item["pod"] == pod_name
+          result << item
+        elsif item["pod"].include?("#{pod_name}/") #子仓库形式
+          result << item
+        end
+      }
+
+      result
+    end
+
+    # 读取依赖yaml(支持锚点变量)，兼容无Psych别名参数的环境
+    def load_dependency_yaml(yaml_path)
+      YAML.load_file(yaml_path, aliases: true)
+    rescue ArgumentError
+      YAML.load_file(yaml_path)
+    end
+
+    # 在所有target依赖文件中定位声明了某pod(root或subspec)的文件
+    # @return [String, nil] 文件绝对路径
+    def locate_pod_dependency_file(pod_name)
+      target_dependency_paths.find do |path|
+        File.read(path) =~ /^- pod:\s+#{Regexp.escape(pod_name)}(\/|\s|$)/
+      end
+    end
+
+    # 主App target对应的依赖文件路径
+    def main_dependency_file
+      File.join(self.path, "#{application_target.name}Dependencies.yaml")
+    end
+
+    # 读取target依赖文件的SOURCES数组(有序)，支持锚点
+    def dependency_sources(yaml_path)
+      content = load_dependency_yaml(yaml_path)
+      content.is_a?(Hash) ? Array(content["SOURCES"]).map(&:to_s) : []
+    end
+
+    # 外科式修改：在不整体重写yaml(保护锚点变量/注释/空行)的前提下，
+    # 更新指定pod块内的字段。block从 "- pod: NAME" 行开始，到缩进层级回到0之前
+    def edit_pod_block(text, pod_name)
+      lines = text.lines
+      start_idx = lines.index { |line| line =~ /^- pod:\s+#{Regexp.escape(pod_name)}\s*$/ }
+      return text unless start_idx
+
+      end_idx = start_idx
+      ((start_idx + 1)...lines.size).each do |idx|
+        break unless lines[idx] =~ /^\s+\S/
+        end_idx = idx
+      end
+
+      block = lines[start_idx..end_idx]
+      new_block = yield(block)
+      (lines[0...start_idx] + Array(new_block) + lines[(end_idx + 1)..-1]).join
+    end
+
+    # 设置pod块内的2空格缩进字段(不存在则插入到pod行之后)
+    def set_block_field(block_lines, field, value)
+      idx = block_lines.index { |line| line =~ /^  #{Regexp.escape(field)}:/ }
+      if idx
+        block_lines[idx] = "  #{field}: #{value}\n"
+      else
+        block_lines.insert(1, "  #{field}: #{value}\n")
+      end
+      block_lines
+    end
+
+    # 删除pod块内的2空格缩进字段
+    def remove_block_field(block_lines, field)
+      block_lines.reject { |line| line =~ /^  #{Regexp.escape(field)}:/ }
+    end
+
+    # 在文件末尾追加一个pod条目(自动补空行)
+    def append_pod_item(text, lines)
+      text = text.end_with?("\n") ? text : "#{text}\n"
+      text += "\n" unless text.end_with?("\n\n")
+      text + lines
+    end
+
+    def create_local_yaml_pod(pod_name, repo_module_source)
+      module_source_path = repo_module_source.path
+      dependency = {}
+      dependency["pod"] = pod_name
+      if repo_module_source.respond_to?(:podspec_at_repo_root?) && !repo_module_source.podspec_at_repo_root?
+        # podspec在子目录(或一仓多组件)时，:path 无法在根目录找到podspec，
+        # 显式指向 update_podspec 生成的 json 文件，CocoaPods 以其所在目录为文件根
+        dependency["podspec"] = repo_module_source.podspec_json_path
+      else
+        dependency["path"] = module_source_path
+      end
+      # 本地覆盖文件默认inhibit_warnings=false，打包场景显式true避免源码警告干扰archive
+      dependency["inhibit_warnings"] = true
+
+      dependency
+
+    end
+
+    # 二进制pod散装头文件兜底：
+    # 源码pod时代 Pods/<组件>/ 下有散装.h，部分组件podspec用相对HEADER_SEARCH_PATHS
+    # (如FMDB的SQLCipher subspec指向"SQLCipher"目录)查找这些文件；组件二进制化后该目录
+    # 只剩.xcframework，同名头文件查找会穿透到系统SDK(如sqlite3.h)，缺少SQLCipher的
+    # codec API声明(sqlite3_key/sqlite3_rekey)导致编译失败。
+    # 这里把xcframework内slice的Headers软链回Pods/<组件>/，恢复与源码pod一致的查找布局；
+    # 已存在同名散装文件的pod不受影响(源码pod场景)，重复执行幂等
+    def restore_vendored_pod_headers
+      pods_dir = File.join(self.path, 'Pods')
+      return unless File.directory?(pods_dir)
+
+      linked_pods = []
+      Dir.children(pods_dir).sort.each do |name|
+        pod_dir = File.join(pods_dir, name)
+        next unless File.directory?(pod_dir)
+
+        headers_dirs = Dir.glob(File.join(pod_dir, '*.xcframework', 'ios-*', '*.framework', 'Headers'))
+        next if headers_dirs.empty?
+
+        linked = 0
+        headers_dirs.each do |headers_dir|
+          Dir.children(headers_dir).sort.each do |header|
+            next unless header.end_with?('.h')
+            link_path = File.join(pod_dir, header)
+            next if File.exist?(link_path)
+            FileUtils.ln_s(File.expand_path(File.join(headers_dir, header)), link_path)
+            linked += 1
+          end
+        end
+        linked_pods << "#{name}(#{linked}个)" if linked > 0
+      end
+
+      unless linked_pods.empty?
+        Build.log.detail("-> 已为二进制pod补齐散装头文件软链: #{linked_pods.join('、')}")
+      end
+    end
+
+    public
+    def archive(repo_module_source)
+
+      # 二进制pod散装头文件兜底(详见方法注释)
+      restore_vendored_pod_headers
+
+      # 检测组件自带的预编译库是否缺 arm64 模拟器 slice，模拟器 archive 时需据此排除 arm64
+      prepare_simulator_arch_compat(repo_module_source)
+
+      # 即时不构建二进制，也要保证真机能够编译成功
+      do_archive(false)
+
+      if repo_module_source.build_item.simulator
+        do_archive(true)
+      else
+        Build.log.info("不构建模拟器")
+      end
+
+      # 打包完成 更新属性
+      update_resource_bundles_paths(repo_module_source)
+      update_resource_paths(repo_module_source)
+
+    end
+
+    public
+    # 校验组件与壳工程的最低iOS版本(只读，不修改任何工程配置)。
+    # CocoaPods对组件target的deployment target取 max(壳工程platform, podspec声明)：
+    #   - 组件要求 <= 壳工程：产物以壳工程版本为准
+    #   - 组件要求 > 壳工程：组件target自动按更高版本编译，pod update不会失败(仅兼容性warning)，
+    #     链接进壳工程也是warning不阻断，无需为单个组件改动公共壳工程
+    def check_package_version(repo_module_source)
+      component_version = repo_module_source.ios_version.to_s.strip
+      shell_version = shell_deployment_target.to_s.strip
+
+      # 壳工程版本读取失败属于异常降级，需要警告提示；podspec未声明平台属正常可空，仅普通提示
+      if shell_version.empty?
+        Build.log.warn("读取壳工程最低iOS版本失败，跳过组件与壳工程的版本融合判断(不影响本次打包)")
+        return
+      end
+      if component_version.empty?
+        Build.log.detail("组件podspec未声明最低iOS版本，壳工程为#{shell_version}，跳过版本融合判断")
+        return
+      end
+
+      effective = Gem::Version.new(component_version) >= Gem::Version.new(shell_version) ? component_version : shell_version
+      Build.log.detail("最低iOS版本：组件podspec #{component_version} | 壳工程 #{shell_version} | 组件产物实际按 #{effective} 编译")
+
+      if Gem::Version.new(component_version) > Gem::Version.new(shell_version)
+        Build.log.warn("组件最低iOS版本(#{component_version})高于壳工程(#{shell_version})：无需修改壳工程，CocoaPods会自动按#{component_version}编译该组件，pod update与链接仅产生兼容性警告、不阻断打包；但该组件在iOS#{shell_version}~#{component_version}系统上运行存在兼容风险，请知悉")
+      end
+    end
+
+    def git_clone(only_head)
+      super
+
+      # clone 后提前校验壳工程存在且 xcodeproj 可正常解析
+      xcodeproj_path = "#{repo_path}/#{scheme}.xcodeproj"
+      Xcodeproj::Project.open(xcodeproj_path)
+    end
+
+    private
+    # 桩化用的最小 main.m：仅依赖系统 UIKit，不引用任何业务组件
+    STUB_MAIN_M = <<~OBJC.freeze
+      //
+      //  main.m
+      //  ⚠️ 本文件由 pod-binary-pack 在组件打包期间临时替换，打包结束后会自动还原，请勿手动修改
+      //
+
+      #import <UIKit/UIKit.h>
+
+      @interface PodBinaryPackBuildAppDelegate : UIResponder <UIApplicationDelegate>
+      @property (nonatomic, strong) UIWindow *window;
+      @end
+
+      @implementation PodBinaryPackBuildAppDelegate
+
+      - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+          self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
+          UIViewController *viewController = [[UIViewController alloc] init];
+          viewController.view.backgroundColor = [UIColor whiteColor];
+          self.window.rootViewController = viewController;
+          [self.window makeKeyAndVisible];
+          return YES;
+      }
+
+      @end
+
+      int main(int argc, char * argv[]) {
+          @autoreleasepool {
+              return UIApplicationMain(argc, argv, nil, NSStringFromClass([PodBinaryPackBuildAppDelegate class]));
+          }
+      }
+    OBJC
+
+    # 壳工程 application target(主App target)，解析结果在本次构建内缓存
+    # @return [Xcodeproj::Project::Object::PBXNativeTarget, nil]
+    def application_target
+      @application_target ||= begin
+        xcodeproj_path = "#{repo_path}/#{scheme}.xcodeproj"
+        project = Xcodeproj::Project.open(xcodeproj_path)
+        project.targets.find do |t|
+          t.product_type.to_s.end_with?('application') &&
+            (t.name == scheme || project.targets.one? { |x| x.product_type.to_s.end_with?('application') })
+        end
+      end
+    end
+
+    # 读取壳工程 application target 的最低iOS部署版本 IPHONEOS_DEPLOYMENT_TARGET
+    # @return [String, nil] 如 "15.0"，读取失败或target不存在返回nil(由调用方决定如何提示)
+    def shell_deployment_target
+      application_target&.common_resolved_build_setting('IPHONEOS_DEPLOYMENT_TARGET')
+    rescue => exception
+      Build.log.detail("读取壳工程IPHONEOS_DEPLOYMENT_TARGET异常：#{exception.message}")
+      nil
+    end
+
+    # 定位 application target 编译源中的 main.m
+    # @return [Pathname, nil]
+    def find_main_m
+      return nil unless application_target
+
+      ref = application_target.source_build_phase.files_references.find do |f|
+        f.path && File.basename(f.path) == 'main.m'
+      end
+      ref&.real_path
+    end
+
+    def stub_main_m
+      main_path = find_main_m
+      unless main_path && File.exist?(main_path)
+        Build.log.warn('未在壳工程 application target 中找到 main.m，跳过 main.m 桩化(若编译报组件找不到请检查工程结构)')
+        @stub_main_m_info = nil
+        return
+      end
+
+      original = File.read(main_path)
+      if original.include?('PodBinaryPackBuildAppDelegate')
+        @stub_main_m_info = nil
+        return
+      end
+
+      @stub_main_m_info = [main_path.to_s, original]
+      File.write(main_path, STUB_MAIN_M)
+      Build.log.detail("已临时桩化 main.m(仅保留 UIKit 最小 AppDelegate): #{main_path}")
+    end
+
+    def restore_main_m
+      return unless @stub_main_m_info
+
+      main_path, original = @stub_main_m_info
+      File.write(main_path, original)
+      @stub_main_m_info = nil
+      Build.log.detail("已还原 main.m 原始内容: #{main_path}")
+    end
+
+    private
+    # 更新编译模式(有configurations声明时按声明判定Debug/Release，
+    # 无声明时保持初始默认false即Release)
+    def __update_debug_mode(pod_item)
+
+      configurations = pod_item["configurations"]
+      unless configurations
+        return
+      end
+
+      if configurations.class == Array
+        res = true
+        configurations.each { |config|
+          # 数组里只要有release 就认为是release包
+          if config.to_s.downcase == "release"
+            res = false
+            break
+          end
+        }
+        @debug_mode = res
+      elsif configurations.class == String
+        @debug_mode = true
+        # 字符串只要包含release 就认为是release
+        if configurations.downcase.include?("release")
+          @debug_mode = false
+        end
+      end
+    end
+
+    # 模拟器架构兼容检测：除组件源码自带的预编译库外，还要扫描 Pods 下所有依赖
+    # (二进制发布的组件以 xcframework 安装)。任一缺 arm64-simulator slice(但有 x86_64 兜底)时，
+    # 模拟器构建需排除 arm64 只出 x86_64。典型场景：
+    #   - YYImage WebP subspec 内置 2016 年版 fat 静态库，arm64 只有真机 slice
+    #   - YBImageBrowser 依赖的 YYImage 二进制 xcframework 只有 ios-arm64 + ios-x86_64-simulator，
+    #     Apple Silicon 模拟器同时构建 arm64+x86_64 时 xcodebuild 报 "Unable to find matching slice"
+    def prepare_simulator_arch_compat(repo_module_source)
+      @simulator_exclude_arm64 = false
+      # 同步到build_item供各仓库提交信息追加 [裁剪架构] 关键字
+      repo_module_source.build_item.simulator_exclude_arm64 = false
+      return unless repo_module_source.build_item.simulator
+
+      # 组件源码自身的 fat framework/静态库(仅检测当前podspec仍声明的vendored库：
+      # 按配置剪掉subspec后，如YYImage去掉WebP，源码里残留的vendored库已不参与编译，
+      # 不应再命中，否则模拟器产物会被误判继续排除arm64)
+      allowed = declared_vendored_binary_paths(repo_module_source)
+      incompatible = detect_device_only_arm64_binaries(repo_module_source.path, allowed_paths: allowed)
+      incompatible.map! { |relative| "组件源码/#{relative}" }
+
+      # Pods 下依赖的 xcframework / fat framework(二进制发布的组件)
+      incompatible.concat(detect_pods_device_only_arm64_binaries)
+
+      return if incompatible.empty?
+
+      @simulator_exclude_arm64 = true
+      # 同步到build_item供各仓库提交信息追加 [裁剪架构] 关键字
+      repo_module_source.build_item.simulator_exclude_arm64 = true
+      Build.log.warn('检测到组件或其依赖缺少 arm64 模拟器 slice，模拟器产物将只构建 x86_64：')
+      incompatible.each { |name| Build.log.warn("  #{name}") }
+      Build.log.warn('Apple Silicon  Mac 上运行该模拟器产物需使用 Rosetta 模式的模拟器；真机产物不受影响')
+    end
+
+    # @return [Array<String>, nil] 当前podspec(可能已按配置剪裁subspec)声明的vendored
+    #   预编译库绝对路径集合；podspec内容不可用时返回nil(调用方回退为全量扫描)。
+    #   spec未声明任何vendored库时返回空数组(源码内不存在参与编译的预编译二进制)
+    def declared_vendored_binary_paths(repo_module_source)
+      content = repo_module_source.respond_to?(:podspec_content) ? repo_module_source.podspec_content : nil
+      return nil unless content.is_a?(Hash)
+
+      specs = repo_module_source.respond_to?(:collect_specs) ? repo_module_source.collect_specs(content) : [content]
+      entries = specs.flat_map do |spec|
+        [spec["vendored_frameworks"], spec["vendored_libraries"],
+         spec["ios"].is_a?(Hash) ? spec["ios"]["vendored_frameworks"] : nil,
+         spec["ios"].is_a?(Hash) ? spec["ios"]["vendored_libraries"] : nil]
+      end.flatten.compact.map(&:to_s)
+      return [] if entries.empty?
+
+      root = repo_module_source.component_root_dir
+      entries.flat_map { |entry| Dir.glob(File.join(root, entry)) }
+             .select { |path| File.exist?(path) }
+             .map { |path| File.expand_path(path) }
+             .uniq
+    end
+
+    # @return [Array<String>] 仅含真机 arm64 slice(且提供 x86_64 兜底)的预编译二进制相对路径。
+    #   allowed_paths 非 nil 时仅保留声明在vendored库内的二进制(按目录前缀匹配)
+    def detect_device_only_arm64_binaries(source_path, allowed_paths: nil)
+      result = vendored_binaries(source_path).select do |bin|
+        archs = `lipo -archs #{Shellwords.escape(bin)} 2>/dev/null`.split
+        next false unless archs.include?('arm64')
+        next false unless archs.include?('x86_64')
+
+        !arm64_slice_supports_simulator?(bin)
+      end
+      unless allowed_paths.nil?
+        result = result.select do |bin|
+          expanded = File.expand_path(bin)
+          allowed_paths.any? { |path| expanded == path || expanded.start_with?(path + File::SEPARATOR) }
+        end
+      end
+      result.map { |bin| bin.sub("#{source_path}/", '') }
+    end
+
+    # 扫描 Pods 目录下各依赖安装的 xcframework / fat framework，
+    # 返回缺 arm64-simulator slice 但有 x86_64-simulator 兜底的框架名(供排除 arm64)
+    def detect_pods_device_only_arm64_binaries
+      pods_root = File.join(self.path, 'Pods')
+      return [] unless Dir.exist?(pods_root)
+
+      incompatible = []
+
+      # 1) xcframework：解析 Info.plist，缺 arm64-simulator 但有 x86_64-simulator 时回退 x86_64
+      Dir.glob(File.join(pods_root, '*', '*.xcframework')).sort.each do |xcframework|
+        next unless xcframework_can_fallback_x86_64?(xcframework)
+
+        incompatible << File.basename(xcframework, '.xcframework')
+      end
+
+      # 2) 老式 fat framework/静态库：按 arm64 slice 平台标记判定
+      incompatible.concat(
+        detect_device_only_arm64_binaries(pods_root)
+          .map { |relative| relative.split(File::SEPARATOR).first }
+      )
+
+      incompatible.uniq
+    end
+
+    # xcframework 模拟器 slice 支持的架构数组；非数组结构时返回 nil
+    def xcframework_simulator_archs(xcframework_path)
+      plist_path = File.join(xcframework_path, 'Info.plist')
+      return nil unless File.exist?(plist_path)
+
+      # 用系统 plutil 转 JSON 解析，避免依赖 CFPropertyList/Xcodeproj::Plist 的具体实现
+      json = `plutil -convert json -o - #{Shellwords.escape(plist_path)} 2>/dev/null`
+      plist = JSON.parse(json) rescue nil
+      libraries = plist.is_a?(Hash) ? plist['AvailableLibraries'] : nil
+      return nil unless libraries.is_a?(Array)
+
+      libraries.select { |lib| lib['SupportedPlatformVariant'] == 'simulator' }
+               .flat_map { |lib| Array(lib['SupportedArchitectures']) }
+    end
+
+    # xcframework 可安全回退为 x86_64-only 模拟器：有模拟器 slice、缺 arm64、但提供 x86_64。
+    # 完全没有模拟器 slice 的库不纳入(那是另一类配置问题，交由链接器报原错)
+    def xcframework_can_fallback_x86_64?(xcframework_path)
+      archs = xcframework_simulator_archs(xcframework_path)
+      return false if archs.nil? || archs.empty?
+
+      !archs.include?('arm64') && archs.include?('x86_64')
+    end
+
+    # 组件源码内的预编译二进制：*.framework/<框架名> 与顶层静态库 *.a；
+    # .xcframework 内部已按平台分 slice 由 ld 自动选择，跳过不检测
+    def vendored_binaries(source_path)
+      result = []
+      Dir.glob(File.join(source_path, '**', '*.framework')).sort.each do |framework|
+        next if framework.include?('.xcframework/')
+
+        binary = File.join(framework, File.basename(framework, '.framework'))
+        result << binary if File.file?(binary)
+      end
+      result.concat(Dir.glob(File.join(source_path, '**', '*.a')).reject { |path| path.include?('.xcframework/') }.sort)
+      # lipo 对非 Mach-O/非归档文件返回非 0，据此过滤掉 Headers 等同名项
+      result.uniq.select do |bin|
+        system("lipo -info #{Shellwords.escape(bin)}", out: File::NULL, err: File::NULL)
+      end
+    end
+
+    # arm64 slice 是否支持模拟器：现代 arm64-simulator 目标必定带
+    # LC_BUILD_VERSION 且 platform 为 7(iOSSimulator)；其余情况(LC_VERSION_MIN_IPHONEOS 或 platform=iOS)均为真机
+    def arm64_slice_supports_simulator?(binary)
+      Tempfile.create(['arm64_slice', '.a']) do |tmp|
+        tmp.close
+        unless system("lipo #{Shellwords.escape(binary)} -thin arm64 -output #{Shellwords.escape(tmp.path)}",
+                      out: File::NULL, err: File::NULL)
+          return false
+        end
+        load_info = `otool -l #{Shellwords.escape(tmp.path)} 2>/dev/null`
+        load_info.include?('LC_BUILD_VERSION') && load_info.match?(/\bplatform\s+7\b/)
+      end
+    end
+
+    private
+    # 打包
+    def do_archive(simulator = false)
+
+      current = Dir.pwd
+      Dir.chdir(self.path)
+
+      product_dir = simulator ? "ios_simulator" : "ios"
+      archive_path = "#{self.path}/build/#{product_dir}"
+      debug_mode_str = debug_mode ? "Debug" : "Release"
+      # generic/platform=iOS Simulator 通用模拟器目标默认按 ARCHS_STANDARD 同时产出
+      # arm64(Apple Silicon模拟器) + x86_64(Intel模拟器)，合并后 slice 目录为 ios-arm64_x86_64-simulator，
+      # 可同时兼容两类Mac。如只需arm64可显式追加 ARCHS=arm64，不要再用已废弃的 VALID_ARCHS
+      destination = simulator ? "iOS Simulator" : "iOS"
+
+      # 记录路径
+      if simulator
+        @simulator_archive_path = "#{archive_path}.xcarchive"
+      else
+        @real_device_archive_path = "#{archive_path}.xcarchive"
+      end
+
+      command = "xcodebuild archive"
+      command += " -workspace \"#{self.xcworkspace}\""
+      command += " -scheme \"#{self.scheme}\""
+      command += " -configuration #{debug_mode_str}"
+      command += " -destination \"generic/platform=#{destination}\""
+
+      if code_signing
+        # 启用签名: 需要 Xcode 已登录对应团队账号并能自动获取描述文件
+        command += " -allowProvisioningUpdates -allowProvisioningDeviceRegistration"
+        command += " DEVELOPMENT_TEAM=#{development_team}" unless development_team.to_s.strip.empty?
+      else
+        # 不签名: 本工具 archive 仅为提取组件 .framework，产物由 App 正式打包时统一签名，
+        # 因此构建机无需任何证书/Apple ID/描述文件
+        command += " CODE_SIGN_IDENTITY=\"\""
+        command += " CODE_SIGNING_REQUIRED=NO"
+        command += " CODE_SIGNING_ALLOWED=NO"
+      end
+
+      command += " -archivePath \"#{archive_path}\""
+      command += " SKIP_INSTALL=NO"
+      command += " BUILD_LIBRARY_FOR_DISTRIBUTION=YES"
+      # 组件自带仅真机 arm64 的预编译库(老 fat framework/静态库)时，模拟器无法产出 arm64 slice，
+      # 强制只构建 x86_64(Apple Silicon 以 Rosetta 运行模拟器)，否则链接报
+      # "building for iOS-simulator but linking object built for iOS"
+      if simulator && @simulator_exclude_arm64
+        command += " EXCLUDED_ARCHS=arm64"
+      end
+      # 默认静默减少日志，--verbose 时输出完整编译日志便于排查失败原因
+      command += " -quiet" unless Build.log.debug_enabled?
+
+      build_type_string = simulator ? "模拟器" : "真机"
+      Build.log.step("开始编译构建#{build_type_string}")
+      Build.log.debug("#{build_type_string}构建命令: #{command}")
+
+      res = system command
+
+      unless res == true
+        Build.log.error("编译失败(#{build_type_string})，构建命令: #{command}")
+        error = "编译失败(#{build_type_string})"
+        pusher.push("❌ 编译失败", error)
+        Process.exit(-1)
+      end
+      Build.log.detail("#{build_type_string}构建完成")
+
+      Dir.chdir(current)
+    end
+
+    private
+    def update_resource_bundles_paths(repo_module_source)
+      applications_path = "#{self.real_device_archive_path}/Products/Applications"
+
+      # 如果只构建模拟器的话  就没有真机的产物， 就从模拟器里找
+      unless Dir.exist?applications_path
+        applications_path = "#{self.simulator_archive_path}/Products/Applications"
+      end
+
+      # 汇总root及所有subspec的resource_bundles(多subspec整包构建)
+      bundle_names = repo_module_source.all_resource_bundle_names
+
+      return if bundle_names.empty?
+
+      # 获取bundle的路径
+      bundle_path_array = Array.new
+      bundle_names.each { |bundle_name|
+        bundle = "#{bundle_name}.bundle"
+        FileHelper.recursion_find(applications_path, bundle, bundle_path_array)
+      }
+      @resource_bundles_paths = bundle_path_array
+    end
+
+    def update_resource_paths(repo_module_source)
+      # 汇总root及所有subspec的resources glob(多subspec整包构建)
+      resources_array = repo_module_source.all_resource_globs
+
+      return if resources_array.empty?
+
+      search_root = repo_module_source.component_root_dir
+      # 遍历配置的资源文件(多glob重叠命中时去重)
+      resources_array.each { |resource|
+        # 原始资源文件路径(podspec所在目录为根)，可能是通配符
+        Dir["#{search_root}/#{resource}"].select{|real_path|
+          @resource_paths << real_path
+        }
+      }
+      @resource_paths.uniq!
+    end
+
+  end
+end