cocoapods-local-override 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 721bbcd4a8edde7fbe840ecc9b0ea60992f2c14fd6e82d851d739ed2abf08141
+  data.tar.gz: 742f596b656dac95e23a447529ef988d67e529f9b2ed4ff1ec045c6867f182fa
+SHA512:
+  metadata.gz: '09c8e22c52e06e23b9199acade0957f06d21fcc55219178633cd0823f613294f0d971909e0bad38efaa0b4a49f1fb532f8be4dacec2fa3d914d620d5b9e85541'
+  data.tar.gz: 7aa64b14d53d6df0edd7af6c1e1566eeea327de8cb72fe84a5d4795aecbde53bc99d090c184bd9853d95fd4a3691a74c0b61c1b0814954a1eee290870b836c69

data/Podfile.local.example

@@ -0,0 +1,22 @@
+# Podfile.local — 本地 pod 切换配置
+# 将该文件放在 Podfile 同级目录，由 cocoapods-local-override 插件自动读取。
+# 不需要在 Podfile 中添加任何 require/load。
+
+# -----------------------------------------------------------------
+# 1. 本地路径替换（将远程 pod 指向本地目录）
+# -----------------------------------------------------------------
+# local_pods:
+#   SomePod: ../path/to/SomePod
+#   AnotherPod: ../path/to/AnotherPod
+
+# -----------------------------------------------------------------
+# 2. 版本号替换
+# -----------------------------------------------------------------
+# replace_versions:
+#   SomePod: 1.2.3
+
+# -----------------------------------------------------------------
+# 3. Git 分支替换（仅对通过 :git + :branch 声明的 pod 生效）
+# -----------------------------------------------------------------
+# replace_branches:
+#   SomeGitPod: develop

data/README.md

@@ -0,0 +1,105 @@
+# cocoapods-local-override
+
+在不修改 Podfile 的前提下，将指定 pod 从远程依赖切换为本地路径（或替换版本号/branch）。
+
+---
+
+## 安装
+
+```bash
+cd Business/Tools/cocoapods-local-override
+gem build cocoapods-local-override.gemspec
+gem install --local cocoapods-local-override-*.gem
+```
+
+验证安装：
+
+```bash
+pod plugins installed | grep local-override
+```
+
+---
+
+## 使用
+
+### 1. 创建配置文件
+
+插件会在首次 `pod install` 时自动从模板 `Podfile.local.example` 创建 `Podfile.local`，无需手动操作。
+
+如需手动创建：
+
+```bash
+cp Tools/cocoapods-local-override/Podfile.local.example Podfile.local
+```
+
+### 2. 编辑 Podfile.local
+
+```yaml
+local_pods:
+  BBreachOrder: ../BusinessLayer/BBreachOrder
+  BMediator: ../CoreLayer/BMediator
+  BaseConfiguration: ../CoreLayer/BaseConfiguration
+  BaseFoundation: ../../BasicLayer/BaseFoundation
+
+replace_versions:
+  SDWebImage: 1.2.3
+
+replace_branches:
+  DeliverGoods: develop-9.6.2
+```
+
+### 3. 执行 pod install
+
+```bash
+pod install
+```
+
+插件自动生效，输出示例：
+
+```
+[ LOCAL ] BTransportationReminder →  ../BusinessLayer/BTransportationReminder
+[ LOCAL ] BBreachOrder            →  ../BusinessLayer/BBreachOrder
+[ LOCAL ] BMediator               →  ../CoreLayer/BMediator
+[ VERSION ] SDWebImage            →  1.2.3
+[ BRANCH ] DeliverGoods           →  develop-9.6.2
+[ LOCAL ] WNDatePicker (via BTransportationReminder) →  ../../BasicLayer/WNDatePicker/
+[+] Added Podfile.local to Pods project
+```
+
+### 4. 恢复远程依赖
+
+注释掉或删除 `Podfile.local` 中对应的条目，或不创建该文件即可恢复远程依赖。
+
+---
+
+## 功能说明
+
+### 三种覆盖模式
+
+| 配置项 | 作用 | 标签 |
+|---|---|---|
+| `local_pods` | 将 pod 替换为 `:path` 指向本地目录 | `[ LOCAL ]` |
+| `replace_versions` | 覆盖 Podfile 中声明的版本号 | `[ VERSION ]` |
+| `replace_branches` | 修改 `:git` 声明的 `:branch` | `[ BRANCH ]` |
+
+三种配置按上述优先级依次匹配，命中的第一个生效。路径不存在时黄色警告并回退远程。
+
+### 传递依赖自动注入
+
+本地 pod 的 podspec 中声明的依赖，如果也在 `local_pods` 配置中但未在 Podfile 显式声明，插件会自动将其注入为目标依赖，确保整个依赖树使用本地版本。
+
+输出格式：`[ LOCAL ] dep_name (via parent) → path`
+
+使用 BFS 遍历依赖树，visited set 防循环引用。
+
+### Podfile.local 在 Pods 工程可见
+
+每次 `pod install` 后，插件自动将 `Podfile.local` 加入 Pods.xcodeproj，排在工程导航栏首位，方便在 Xcode 中直接查看和编辑。
+
+### 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `COCOAPODS_LOCAL_OVERRIDE_DISABLE=1` | 禁用插件 |
+| `COCOAPODS_LOCAL_OVERRIDE_CONFIG=/path/config.yml` | 指定自定义配置文件路径 |
+

data/lib/cocoapods_plugin.rb

@@ -0,0 +1,659 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# cocoapods-local-override — CocoaPods 本地覆盖插件
+# =============================================================================
+#
+# 概述
+# ----
+# 在不需要修改 Podfile 的情况下，从 Podfile.local（YAML）读取配置，
+# 将指定的 pod 从远程依赖切换为本地路径 / 替换版本号 / 替换分支。
+#
+# 加载机制
+# -------
+# CocoaPods 启动时自动扫描已安装 gem 中的 `cocoapods_plugin.rb` 并
+# 在沙箱加载上下文执行，**不需要在 Podfile 中 require**。
+#
+# 三大核心功能
+# -----------
+# 1. pod 覆盖     — 劫持 Podfile#pod，将 local/version/branch 替换插入声明阶段。
+# 2. 传递依赖注入  — 本地 pod 的 podspec 依赖著也在 local_pods 里时，自动注入到根 target。
+# 3. Pods 工程可见 — post_install 将 Podfile.local 添加到 Pods.xcodeproj 导航栏首位。
+#
+# === 环境变量 ===
+#   COCOAPODS_LOCAL_OVERRIDE_DISABLE=1   设为 1/true/yes 时禁用所有覆盖
+#   COCOAPODS_LOCAL_OVERRIDE_CONFIG      指定自定义 YAML 配置文件路径（默认 Podfile.local）
+
+# 依赖库：YAML 解析 / 路径处理 / 集合去重
+require 'yaml'
+require 'pathname'
+require 'set'
+
+module CocoaPodsLocalOverride
+  # ===========================================================================
+  # 模块常量
+  # ===========================================================================
+
+  # 默认配置文件名（放在 Podfile 同级目录）
+  CONFIG_FILE_NAME = 'Podfile.local'
+  # 禁用插件的环境变量名
+  ENV_DISABLE_KEY  = 'COCOAPODS_LOCAL_OVERRIDE_DISABLE'
+  # 自定义配置文件路径的环境变量名
+  ENV_CONFIG_KEY   = 'COCOAPODS_LOCAL_OVERRIDE_CONFIG'
+
+  # 插件自身的根目录（gem 安装根路径），用于定位模板文件
+  PLUGIN_ROOT = File.expand_path('..', __dir__).freeze
+  # 模板文件：当 Podfile.local 不存在时自动从该文件复制创建
+  EXAMPLE_FILE = 'Podfile.local.example'
+
+  # ===========================================================================
+  # 模块实例变量（相当于模块级状态）
+  # ===========================================================================
+
+  # @config           — 已解析的 YAML 配置 Hash，结构:
+  #   { 'local_pods' => {name => path}, 'replace_versions' => {...}, 'replace_branches' => {...} }
+  # @config_loaded    — 防止重复加载配置的标记位
+  # @disabled         — 缓存禁用状态（首次读取环境变量后缓存）
+  # @max_name_len     — 所有 pod 名称的最大长度，用于输出对齐
+  @config = nil
+  @config_loaded = false
+  @disabled = nil
+  @max_name_len = 0
+
+  # ===========================================================================
+  # 终端 ANSI 颜色常量
+  # ===========================================================================
+  #
+  # 颜色体系：
+  #   C_RESET / C_DIM — 重置与弱化（箭头、箭头两边的空格等辅助元素）
+  #   C_CYAN           — 主要信息展示色（pod 路径/版本号/分支名等值）
+  #   C_GREEN          — 成功信息（[+] 前缀、配置创建等正面状态）
+  #   C_YELLOW         — 警告信息（[x] 前缀、路径不存在等异常状态）
+  #   C_MAGENTA        — 未使用（保留）
+  #   C_RED            — 未使用（保留）
+  #   LABEL_COLORS     — 标签专用色：蓝绿色系渐变，视觉统一但不突兀
+
+  C_RESET   = "\e[0m"   # 重置所有样式
+  C_DIM     = "\e[2m"   # 暗淡/弱化效果（用于箭头 → 等辅助元素）
+  C_CYAN    = "\e[36m"  # 青色（用于显示的路径/版本/分支名等值）
+  C_GREEN   = "\e[32m"  # 绿色（[+] 成功前缀）
+  C_YELLOW  = "\e[33m"  # 黄色（[x] 警告前缀）
+  C_MAGENTA = "\e[35m"  # 品红（保留未使用）
+  C_RED     = "\e[31m"  # 红色（保留未使用）
+
+  # pod 值的颜色映射（用于显示的路径/版本号/分支名等）
+  COLORS = {
+    local:   C_CYAN,
+    version: C_GREEN,
+    branch:  C_MAGENTA
+  }.freeze
+
+  # 标签颜色映射（[ LOCAL ] / [ VERSION ] / [ BRANCH ] 颜色）
+  # 使用 256 色调色板，蓝绿色系渐变：绿→青→蓝，同色系但有区分度
+  LABEL_COLORS = {
+    local:   "\e[38;5;120m",  # 春绿
+    version: "\e[38;5;80m",   # 青蓝
+    branch:  "\e[38;5;39m"    # 湖蓝
+  }.freeze
+
+  # 标签文字映射
+  LABELS = {
+    local:   '[ LOCAL ]',
+    version: '[ VERSION ]',
+    branch:  '[ BRANCH ]'
+  }.freeze
+
+  # ===========================================================================
+  # 环境变量检测
+  # ===========================================================================
+
+  # 检查插件是否被环境变量禁用
+  # 首次调用时读取 COCOAPODS_LOCAL_OVERRIDE_DISABLE，结果缓存到 @disabled。
+  # 支持的值: 1, true, yes（不区分大小写）
+  # @return [Boolean] true 表示已禁用
+  def self.disabled?
+    return @disabled unless @disabled.nil?
+
+    val = ENV[ENV_DISABLE_KEY]
+    # 仅当环境变量值为 1 / true / yes 时才算禁用
+    @disabled = %w[1 true yes].include?(val.to_s.downcase)
+    if @disabled
+      Pod::UI.puts "#{C_DIM}[i] cocoapods-local-override disabled by #{ENV_DISABLE_KEY}=#{val}#{C_RESET}"
+    end
+    @disabled
+  end
+
+  # 定位配置文件路径，优先级：
+  #   1. 环境变量 COCOAPODS_LOCAL_OVERRIDE_CONFIG 指定的路径
+  #   2. 默认：Podfile 所在目录/Podfile.local
+  #   3. 兜底：当前工作目录/Podfile.local
+  # @return [String] 配置文件绝对路径
+  def self.find_config_path
+    # 优先使用环境变量指定的自定义路径
+    custom = ENV[ENV_CONFIG_KEY]
+    unless custom.to_s.strip.empty?
+      custom = custom.strip
+      if File.exist?(custom)
+        return custom
+      else
+        Pod::UI.warn "#{C_YELLOW}[x] #{ENV_CONFIG_KEY}=#{custom} not found, fallback to default#{C_RESET}"
+      end
+    end
+
+    # 默认：从 Podfile 所在目录拼接 Podfile.local
+    podfile = begin
+                Pod::Config.instance.podfile_path
+              rescue StandardError
+                nil
+              end
+    base = podfile ? File.dirname(podfile) : Dir.pwd
+    File.join(base, CONFIG_FILE_NAME)
+  end
+
+  # ===========================================================================
+  # 自动创建配置文件
+  # ===========================================================================
+
+  # 如果 Podfile.local 不存在，从 gem 内置的 Podfile.local.example 模板
+  # 复制一份到 Podfile 同级目录，方便开发者快速上手。
+  # @param config_path [String] 目标配置文件路径
+  def self.ensure_config_file(config_path)
+    return if File.exist?(config_path)
+
+    example_path = File.join(PLUGIN_ROOT, EXAMPLE_FILE)
+
+    unless File.exist?(example_path)
+      Pod::UI.warn "#{C_YELLOW}[x] Template #{EXAMPLE_FILE} not found in gem#{C_RESET}"
+      return
+    end
+
+    begin
+      # 确保目标目录存在
+      FileUtils.mkdir_p(File.dirname(config_path))
+      # 复制模板文件（copy_file 保留原始文件权限）
+      FileUtils.copy_file(example_path, config_path)
+      Pod::UI.puts "#{C_GREEN}[+] Created #{File.basename(config_path)} from #{EXAMPLE_FILE}#{C_RESET}"
+    rescue StandardError => e
+      Pod::UI.warn "#{C_YELLOW}[x] Failed to create #{config_path}: #{e.message}#{C_RESET}"
+    end
+  end
+
+  # ===========================================================================
+  # 配置加载与解析
+  # ===========================================================================
+
+  # 加载并解析 Podfile.local（YAML 格式），结果缓存到 @config。
+  # 典型配置结构:
+  #   local_pods:        { PodName: "../relative/path" }
+  #   replace_versions:  { PodName: "1.2.3" }
+  #   replace_branches:  { PodName: "develop-x.y.z" }
+  #
+  # @return [Hash] 解析后的配置 Hash，含 local_pods / replace_versions / replace_branches 三个 key
+  def self.load_config
+    return @config if @config_loaded
+
+    @config_loaded = true
+
+    # 环境变量禁用时直接返回空配置，不执行后续逻辑
+    if disabled?
+      @config = {}
+      return @config
+    end
+
+    config_path = find_config_path
+
+    # 文件不存在则自动创建模板
+    ensure_config_file(config_path)
+
+    # 创建后仍可能为空（如环境变量指定了不存在的文件）
+    unless File.exist?(config_path)
+      @config = {}
+      return @config
+    end
+
+    # 解析 YAML，使用 safe_load（Psych 默认行为）
+    raw = YAML.load_file(config_path)
+    @config = {
+      'local_pods'       => normalize_hash(raw&.dig('local_pods')),
+      'replace_versions' => normalize_hash(raw&.dig('replace_versions')),
+      'replace_branches' => normalize_hash(raw&.dig('replace_branches'))
+    }
+
+    # 计算所有 pod 名称的最大长度，用于输出时的列对齐
+    all_names = @config.values.flat_map(&:keys)
+    @max_name_len = all_names.map(&:length).max || 0
+    @config
+  rescue Psych::SyntaxError => e
+    Pod::UI.warn "#{C_YELLOW}[x] YAML parse error in #{File.basename(config_path)}: #{e.message}#{C_RESET}"
+    @config = {}
+  rescue StandardError => e
+    Pod::UI.warn "#{C_YELLOW}[x] Failed to load #{File.basename(config_path)}: #{e.message}#{C_RESET}"
+    @config = {}
+  end
+
+  # ===========================================================================
+  # 配置便捷访问器
+  # ===========================================================================
+
+  # @return [Hash] 本地 pod 映射表 {name => relative_path}
+  def self.local_pods
+    load_config['local_pods']
+  end
+
+  # @return [Hash] 版本替换映射表 {name => version_string}
+  def self.replace_versions
+    load_config['replace_versions']
+  end
+
+  # @return [Hash] 分支替换映射表 {name => branch_name}
+  def self.replace_branches
+    load_config['replace_branches']
+  end
+
+  # ===========================================================================
+  # monkey-patch: 劫持 Podfile#pod 方法
+  # ===========================================================================
+  #
+  # 核心思路：
+  #   在 Podfile 解析阶段，用 alias_method 保存原始的 pod 方法，
+  #   然后用自定义方法替换它。自定义方法根据 YAML 配置决定实际调用参数：
+  #     - local_pods 命中   → pod 'Name', :path => '/local/abs/path'
+  #     - replace_versions   → pod 'Name', 'X.Y.Z'
+  #     - replace_branches   → pod 'Name', :branch => 'develop-x.y.z'
+  #     - 无匹配             → 原样转发给原始 pod 方法
+  #
+  # 安全措施：
+  #   - @podfile_hook_applied 标记防止重复安装
+  #   - method_defined? 检查防止多次 alias（幂等）
+  #   - 被禁用或配置为空时跳过安装
+
+  # 拦截 Podfile#pod 方法：根据 Podfile.local 配置改写 pod 声明
+  # 在模块底部自动调用（加载即生效）
+  def self.apply_podfile_hook!
+    return if @podfile_hook_applied
+
+    # 预加载配置以触发 @max_name_len 计算
+    load_config
+
+    # 如果被禁用或配置为空，不安装钩子
+    if disabled? || all_config_empty?
+      @podfile_hook_applied = true
+      return
+    end
+
+    # 打开 Pod::Podfile 的单例类（class_eval），注入自定义 pod 方法
+    Pod::Podfile.class_eval do
+      # 幂等检查：如果已经 alias 过则跳过
+      unless method_defined?(:local_override_original_pod)
+        # 1. 保存原始 pod 方法
+        alias_method :local_override_original_pod, :pod
+
+        # 2. 定义新的 pod 方法，加入覆盖逻辑
+        define_method :pod do |*args|
+          pod_name = args[0].to_s
+
+          # 获取当前配置（每次调用都实时获取，但不触发重复解析）
+          local_pods       = CocoaPodsLocalOverride.local_pods
+          replace_versions = CocoaPodsLocalOverride.replace_versions
+          replace_branches = CocoaPodsLocalOverride.replace_branches
+
+          # 按优先级匹配：local > version > branch > 原始调用
+          if local_pods && local_pods.key?(pod_name)
+            handle_local(pod_name, local_pods[pod_name], args)
+          elsif replace_versions && replace_versions.key?(pod_name)
+            handle_version(pod_name, replace_versions[pod_name])
+          elsif replace_branches && replace_branches.key?(pod_name)
+            handle_branch(pod_name, replace_branches[pod_name], args)
+          else
+            # 未命中任何覆盖，调用原始方法
+            local_override_original_pod(*args)
+          end
+        end
+
+        # =====================================================================
+        # 私有辅助方法（注入 Pod::Podfile 实例）
+        # =====================================================================
+
+        private
+
+        # 处理 local 类型覆盖：将 pod 指向本地绝对路径
+        # 路径不存在时回退到远程版本，避免构建中断
+        define_method :handle_local do |name, dev_path, original_args|
+          # 相对路径 → 基于 Podfile 目录计算绝对路径
+          abs_path = resolve_absolute_path(dev_path)
+
+          if File.directory?(abs_path)
+            # 打印覆盖信息，格式: [ LOCAL ] PodName → ../relative/path
+            Pod::UI.puts CocoaPodsLocalOverride.format_pod_line(:local, name, dev_path)
+            # 使用 :path 选项指向本地目录，:inhibit_warnings => false 保留编译警告
+            local_override_original_pod(name, :path => abs_path, :inhibit_warnings => false)
+          else
+            Pod::UI.warn "#{CocoaPodsLocalOverride::C_YELLOW}[x] path not found: #{abs_path}, use remote for #{name}#{CocoaPodsLocalOverride::C_RESET}"
+            local_override_original_pod(*original_args)
+          end
+        end
+
+        # 处理 version 类型覆盖：将 pod 锁定到指定版本号
+        define_method :handle_version do |name, new_version|
+          Pod::UI.puts CocoaPodsLocalOverride.format_pod_line(:version, name, new_version)
+          # 直接传递版本号字符串作为第二个位置参数
+          local_override_original_pod(name, new_version, :inhibit_warnings => false)
+        end
+
+        # 处理 branch 类型覆盖：将 pod 的 :branch 选项替换为目标分支
+        # 前提：原始声明中第二个参数必须是 Hash（如 pod 'X', :git => '...', :branch => '...'）
+        define_method :handle_branch do |name, new_branch, args|
+          Pod::UI.puts CocoaPodsLocalOverride.format_pod_line(:branch, name, new_branch)
+
+          args_copy = args.dup
+          if args_copy[1].is_a?(Hash)
+            # 合并 :branch key，覆盖原始值
+            args_copy[1] = args_copy[1].merge(:branch => new_branch)
+          else
+            # 第二个参数不是 Hash 时无法安全替换，跳过并警告
+            Pod::UI.warn "#{CocoaPodsLocalOverride::C_YELLOW}[x] #{name}: 2nd arg not Hash, branch replace skipped#{CocoaPodsLocalOverride::C_RESET}"
+          end
+          local_override_original_pod(*args_copy)
+        end
+
+        # 将相对路径转换为基于 Podfile 所在目录的绝对路径
+        # 已是绝对路径则原样返回
+        define_method :resolve_absolute_path do |rel_path|
+          p = Pathname.new(rel_path)
+          return rel_path if p.absolute?
+
+          # 基准目录：Podfile 所在目录，兜底为当前工作目录
+          base = begin
+                   File.dirname(Pod::Config.instance.podfile_path)
+                 rescue StandardError
+                   Dir.pwd
+                 end
+          File.expand_path(rel_path, base)
+        end
+      end
+    end
+
+    @podfile_hook_applied = true
+  end
+
+  # ===========================================================================
+  # 工具方法
+  # ===========================================================================
+
+  # 检查所有配置项是否均为空（包括 nil 和空 Hash）
+  # 用于快速判断是否需要安装 monkey-patch，避免无配置时浪费性能
+  # @return [Boolean]
+  def self.all_config_empty?
+    cfg = load_config
+    cfg.values.all? { |v| v.nil? || v.empty? }
+  end
+
+  # 格式化输出一行 pod 覆盖信息，格式示例：
+  #   [ LOCAL ] BatchGoodsManager  →  ../BusinessLayer/BatchGoodsManager
+  #   [ VERSION ] MyPod            →  1.2.3
+  #   [ BRANCH ] DeliverGoods      →  develop-9.6.2
+  #
+  # @param category [Symbol] :local / :version / :branch
+  # @param name      [String] pod 名称（自动对齐到 @max_name_len）
+  # @param value     [String] 显示的值（路径、版本号或分支名）
+  # @param via       [String, nil] 可选，传递依赖的上级 pod 名称，输出为 (via xxx)
+  # @return [String] 格式化后的 ANSI 颜色字符串
+  def self.format_pod_line(category, name, value, via: nil)
+    label  = LABELS[category]
+    if via
+      via_visible = " (via #{via})"
+      name_str    = "#{name}#{C_DIM}#{via_visible}#{C_RESET}"
+      pad_len     = [@max_name_len - name.length - via_visible.length, 0].max
+      padded      = "#{name_str}#{' ' * pad_len}"
+    else
+      padded = name.ljust(@max_name_len)
+    end
+    "#{LABEL_COLORS[category]}#{label}#{C_RESET} #{padded} #{C_DIM}→#{C_RESET}  #{C_CYAN}#{value}#{C_RESET}"
+  end
+
+  # 标准化 YAML 中的 Hash 值：
+  #   1. 所有 key 转为 String 并 strip 空白
+  #   2. 所有 value 转为 String 并 strip 空白
+  #   3. 跳过空 key
+  #   4. nil 或非 Hash 输入返回空 {}
+  # @param raw [Object] YAML 解析后的原始值
+  # @return [Hash{String => String}]
+  def self.normalize_hash(raw)
+    return {} if raw.nil? || !raw.is_a?(Hash)
+    raw.each_with_object({}) do |(k, v), h|
+      h[k.to_s.strip] = v.to_s.strip unless k.to_s.strip.empty?
+    end
+  end
+
+  # ===========================================================================
+  # monkey-patch: 将 Podfile.local 加入 Pods 工程导航栏
+  # ===========================================================================
+  #
+  # 在 post_install 阶段，CocoaPods 生成并保存 .xcodeproj 后，
+  # 将 Podfile.local 作为文件引用添加到 Pods 工程导航栏的第一个位置。
+  # 这样开发者在 Xcode 中可以直接查看和编辑配置文件。
+
+  # 安装 Pods 工程钩子：拦截 create_and_save_projects 以添加 Podfile.local
+  def self.apply_pods_project_hook!
+    return if @pods_project_hook_applied
+    # 触发配置加载（可能在 Podfile 不存在时触发自动创建）
+    load_config
+    @pods_project_hook_applied = true
+
+    Pod::Installer.class_eval do
+      unless method_defined?(:local_override_original_create_and_save_projects)
+        alias_method :local_override_original_create_and_save_projects, :create_and_save_projects
+
+        # 在原始方法执行完后，额外将 Podfile.local 添加到生成的 Pods 工程中
+        define_method :create_and_save_projects do |*args|
+          local_override_original_create_and_save_projects(*args)
+
+          CocoaPodsLocalOverride.add_local_config_to_project(@generated_projects)
+        end
+      end
+    end
+  end
+
+  # 将 Podfile.local 添加到 Pods.xcodeproj 的主 Group 中，并移至首位
+  #
+  # @param generated_projects [Array<Xcodeproj::Project>] CocoaPods 生成的工程列表
+  def self.add_local_config_to_project(generated_projects)
+    config_path = find_config_path
+    return unless File.exist?(config_path)
+
+    # 遍历所有生成的工程（通常只有 Pods.xcodeproj 一个）
+    Array(generated_projects).each do |project|
+      next unless project
+
+      filename = File.basename(config_path)
+
+      # 检查是否已经添加过（避免重复添加）
+      already_added = project.files.any? do |f|
+        f.path == filename || f.path == config_path ||
+          (f.real_path.to_s == File.expand_path(config_path) rescue false)
+      end
+      next if already_added
+
+      # 作为文件引用添加到工程
+      project.add_podfile(config_path)
+
+      # 将 Podfile.local 移到第一个位置（排在 Podfile 前面）
+      main_group = project.main_group
+      local_ref = main_group.children.find { |f| f.path == filename }
+
+      if local_ref
+        idx = main_group.children.index(local_ref)
+        if idx && idx > 0
+          # 移除后插入到首位
+          main_group.children.delete_at(idx)
+          main_group.children.insert(0, local_ref)
+        end
+      end
+
+      project.save
+      Pod::UI.puts "#{C_GREEN}[+] Added #{filename} to Pods project#{C_RESET}"
+    end
+  end
+
+  # ===========================================================================
+  # 传递依赖自动注入
+  # ===========================================================================
+  #
+  # 问题场景：
+  #   假设 Podfile 声明了 pod 'A'（本地覆盖），而 A 的 podspec 依赖 B。
+  #   如果 B 也在 local_pods 中但 Podfile 未显式声明，则 CocoaPods 会从
+  #   远程仓库拉取 B（而非使用本地版本），导致版本不一致或本地修改不生效。
+  #
+  # 解决方案：
+  #   在 resolve_dependencies 之前，用 BFS 遍历所有已在 Podfile 中声明且
+  #   在 local_pods 中的 pod 的 podspec 依赖树。对于每个也在 local_pods 中
+  #   但未在 Podfile 中显式声明的依赖，自动通过 root_td.store_pod 注入到
+  #   根 target definition。
+  #
+  # 安全性：
+  #   - visited set 防止循环依赖导致无限循环
+  #   - declared_names set 跳过已声明 pod，防止重复注入
+
+  # 从本地 pod 目录中查找 podspec 文件
+  # 优先按 pod 名称查找（Name.podspec / Name.podspec.json），
+  # 回退到扫描目录下任意 podspec。
+  #
+  # @param local_path [String] pod 本地目录绝对路径
+  # @param pod_name   [String] pod 名称（可选，用于精确匹配）
+  # @return [String, nil] podspec 文件路径，未找到返回 nil
+  def self.resolve_podspec_path(local_path, pod_name = nil)
+    return nil unless File.directory?(local_path)
+
+    # 优先按 pod 名称查找（更精确）
+    if pod_name && !pod_name.strip.empty?
+      [File.join(local_path, "#{pod_name}.podspec"),
+       File.join(local_path, "#{pod_name}.podspec.json")].each do |c|
+        return c if File.exist?(c)
+      end
+    end
+
+    # 回退：找目录下任意 .podspec（Ruby 格式优先于 JSON）
+    (Dir.glob(File.join(local_path, '*.podspec')) +
+     Dir.glob(File.join(local_path, '*.podspec.json'))).first
+  end
+
+  # BFS 遍历依赖树，将未声明但已在 local_pods 中的传递依赖自动注入
+  #
+  # @param podfile [Pod::Podfile] 当前 Podfile 实例
+  def self.inject_transitive_local_pods(podfile)
+    lp = local_pods
+    return if lp.nil? || lp.empty?
+
+    # 确定 Podfile 所在目录（用于计算相对路径的绝对路径）
+    podfile_dir = begin
+                    File.dirname(podfile.defined_in_file || Dir.pwd)
+                  rescue StandardError
+                    Dir.pwd
+                  end
+
+    # 收集 Podfile 中已显式声明的所有 pod 名称
+    declared_names = Set.new
+    podfile.target_definitions.each_value do |td|
+      td.non_inherited_dependencies.each { |dep| declared_names.add(dep.name) }
+    end
+
+    # BFS 初始化：起始队列 = 已声明且同时存在于 local_pods 中的 pod
+    visit_queue = declared_names.select { |n| lp.key?(n) }
+    visited = Set.new(visit_queue)  # 已访问集合，防止循环依赖
+
+    # 获取根 target definition（Pods），后续注入都在这里进行
+    root_td = podfile.target_definitions['Pods'] || podfile.target_definitions.values.first
+    return unless root_td
+
+    # BFS 主循环
+    while (name = visit_queue.shift)
+      # 计算本地路径的绝对路径
+      abs_path = File.expand_path(lp[name], podfile_dir)
+      podspec_path = resolve_podspec_path(abs_path, name)
+
+      unless podspec_path
+        Pod::UI.warn "#{C_YELLOW}[x] #{name}: no podspec found in #{abs_path}#{C_RESET}"
+        next
+      end
+
+      # 解析 podspec 获取依赖列表
+      begin
+        spec = Pod::Specification.from_file(podspec_path)
+      rescue StandardError => e
+        Pod::UI.warn "#{C_YELLOW}[x] #{name}: failed to parse #{podspec_path} — #{e.message}#{C_RESET}"
+        next
+      end
+
+      # 遍历每个依赖
+      spec.dependencies.each do |dep|
+        # 兼容不同的依赖表示：Pod::Dependency 或 [name, requirement] 数组
+        dep_name = dep.respond_to?(:name) ? dep.name : dep.first
+        dep_name = dep_name.to_s
+
+        # 跳过不在 local_pods 中的依赖
+        next unless lp.key?(dep_name)
+        # 跳过已在 Podfile 中显式声明的依赖
+        next if declared_names.include?(dep_name)
+        # 跳过已访问过的依赖（防止循环）
+        next if visited.include?(dep_name)
+
+        dep_rel_path = lp[dep_name]
+        dep_abs_path = File.expand_path(dep_rel_path, podfile_dir)
+
+        unless File.directory?(dep_abs_path)
+          Pod::UI.warn "#{C_YELLOW}[x] #{dep_name} (dep of #{name}): path not found #{dep_abs_path}#{C_RESET}"
+          next
+        end
+
+        # 注入到根 target definition 中
+        root_td.store_pod(dep_name, :path => dep_abs_path, :inhibit_warnings => false)
+        declared_names.add(dep_name)   # 标记为已声明，防止后续重复注入
+        visited.add(dep_name)          # 标记为已访问
+        visit_queue.push(dep_name)     # 加入队列继续 BFS
+
+        Pod::UI.puts CocoaPodsLocalOverride.format_pod_line(:local, dep_name, dep_rel_path, via: name)
+      end
+    end
+  end
+
+  # 安装传递依赖注入钩子：在 resolve_dependencies 执行前注入
+  def self.apply_transitive_dependency_hook!
+    return if @transitive_dependency_hook_applied
+    load_config
+
+    # 禁用或没有本地 pod 时跳过
+    if disabled? || local_pods.nil? || local_pods.empty?
+      @transitive_dependency_hook_applied = true
+      return
+    end
+
+    Pod::Installer.class_eval do
+      unless method_defined?(:local_override_original_resolve_deps)
+        alias_method :local_override_original_resolve_deps, :resolve_dependencies
+
+        # 在依赖解析之前注入传递依赖，确保本地版本优先被解析
+        define_method :resolve_dependencies do
+          CocoaPodsLocalOverride.inject_transitive_local_pods(podfile)
+          local_override_original_resolve_deps
+        end
+      end
+    end
+
+    @transitive_dependency_hook_applied = true
+  end
+
+  # ===========================================================================
+  # 启动入口：模块加载时自动安装所有钩子
+  # ===========================================================================
+  #
+  # 执行顺序：
+  #   1. apply_podfile_hook!              — 劫持 pod() 方法（Podfile 解析阶段）
+  #   2. apply_pods_project_hook!         — post_install 阶段添加 Podfile.local 到工程
+  #   3. apply_transitive_dependency_hook! — resolve_dependencies 前注入传递依赖
+  #
+  # 三个钩子各自独立，被禁用或配置为空时优雅跳过。
+
+  apply_podfile_hook!
+  apply_pods_project_hook!
+  apply_transitive_dependency_hook!
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: cocoapods-local-override
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- zhaocw
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-27 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      自动读取项目根目录下的 Podfile.local (YAML 格式)，
+      在不修改 Podfile 的情况下，将指定的 pod 从远程依赖切换为本地路径依赖。
+      也支持替换版本号和 git 分支。
+
+      Podfile.local 示例：
+      local_pods:
+        SomePod: ../path/to/SomePod
+        AnotherPod: ../path/to/AnotherPod
+      replace_versions:
+        SomePod: 1.2.3
+      replace_branches:
+        SomePod: develop
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Podfile.local.example
+- README.md
+- lib/cocoapods_plugin.rb
+homepage: https://git.code.tencent.com/zczy/ios/cocoapods-local-override
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: 'CocoaPods plugin: override remote pods with local paths without modifying
+  Podfile.'
+test_files: []