cocoapods-meitu-bin 3.0.2 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f8e34d0eef3e6ae1258472fabbb4750d205a2dee56a51f40b827d95597e0c56
-  data.tar.gz: c589ba529578d252e84bb7dd2d702c19a3d4d7a64d0d78c53892db2839946e4b
+  metadata.gz: 02cd60b43188e551ce7bcadb27453077e9e23353e1470e2d2f3396e901201c9b
+  data.tar.gz: 7431d9db2c1f969a60ef6c65f11e1098d9501a5b33c8c102e89c59cd68d8910c
 SHA512:
-  metadata.gz: da4f7e694226ced238d9e4d89ebfaafcb3263fbb826e5ab58f4c818baef34357f86ad9b40081e438b1162e735d5955be0425f6b84a24e91a883c9006377accf3
-  data.tar.gz: 04b73ddef551f520b5b89f4406e5e6dd015adf814e3504d1f062300e6339d11139d7b45863f66eaf735c5aec2c909edff5b9c454eefd95e698f9975359bd5b59
+  metadata.gz: 91f2b8468a6b747ab6a69e9ed0d5c61c138f73e3e2624c31f169ec85c8be15aecb799353031211b641179e779f8ba2eb41807f465c6f88b3d267ed7e3cbe8cb6
+  data.tar.gz: 70f76e6bbfc54db74e5bd310054747407e87e1be33987ccb3ecdd33e0d970cadc1bb841860e4b7d8e1d8d5177e137dc81225ed3630732ebf8405648a241b8fbd

data/README.md

@@ -2,57 +2,296 @@
 
 ## 简介
 
-`cocoapods-meitu-bin`是`CocoaPods`的二进制插件，提供了二进制相关的功能，如基于壳工程的二进制制作、二进制 / 源码切换等
+`cocoapods-meitu-bin` 是 `CocoaPods` 的二进制插件，提供两类核心能力：
 
-[美图秀秀 iOS 客户端二进制之路](https://juejin.cn/post/7175023366783385659)
+1. 基于壳工程/组件工程制作二进制（`pod bin build-all`）。
+2. 在 `pod install` 期间动态切换源码与二进制（含 monorepo `:path` 组件）。
+
+对应 monorepo `:path` 动态切换的关键实现可参考提交：`6ca9994`（`support worktree identity for local path pods`）。
 
 ## 安装
 
-`cocoapods-meitu-bin`有2种安装方式：
+支持两种方式：
 
-* 安装到本机目录
-* 使用`Gemfile`
+1. 安装到本机 RubyGems。
+2. 通过项目 `Gemfile` 管理。
 
-### 安装到本机目录
+### 方式 1：安装到本机
 
 ```shell
-$ sudo gem install cocoapods-meitu-bin
+sudo gem install cocoapods-meitu-bin
 ```
-    
-### 使用Gemfile
 
-在`Gemfile`中添加如下代码，然后执行`bundle install`
+### 方式 2：Gemfile
+
+在 `Gemfile` 中添加：
 
 ```ruby
 gem 'cocoapods-meitu-bin'
 ```
 
-## 使用
+然后执行：
+
+```shell
+bundle install
+```
+
+## 快速使用
+
+### 1) Podfile 开启二进制
+
+```ruby
+plugin 'cocoapods-meitu-bin'
+
+# true: 开启二进制；false: 全源码
+use_binaries!(ENV['MEITU_USE_BINARIES'] != 'false')
+
+# 源码白名单（这些组件强制走源码）
+set_use_source_pods ['WCDBSwift']
+
+# 可选：按环境切换二进制配置（Debug / Release / Distribution）
+set_configuration(ENV['MEITU_USE_CONFIGURATION'] || 'Debug')
+```
+
+### 2) monorepo 本地 `:path` 接入示例
+
+```ruby
+MTXX_MONOREPO_ROOT = File.expand_path('../../..', __dir__)
+MTXX_MONOREPO_POD_PATHS = {
+  'MTVIPModule' => 'Modules/MTVIPModule',
+  'MTImageEditor' => 'Modules/MTXXImageModule'
+}.freeze
+
+def mtxx_monorepo_pod(name, fallback = nil, fallback_options = nil)
+  if MTXX_MONOREPO_POD_PATHS.key?(name)
+    options = { :path => File.join(MTXX_MONOREPO_ROOT, MTXX_MONOREPO_POD_PATHS[name]) }
+    pod name, options
+  elsif fallback_options
+    pod name, fallback, fallback_options
+  elsif fallback
+    pod name, fallback
+  else
+    pod name
+  end
+end
+
+target 'MTXX' do
+  mtxx_monorepo_pod 'MTVIPModule'
+  mtxx_monorepo_pod 'MTImageEditor'
+end
+```
+
+## Monorepo 专章：`:path` 组件动态切换（重点）
+
+本节专门说明 monorepo 下本地 `:path` 组件如何在一次 `pod install` 中动态决定“走源码”还是“走二进制”。
+
+### 目标与结论
+
+1. 目标：本地组件有改动就切源码，没改动且二进制可用就切 binary。
+2. 结论：判定依据不是单一 commit，而是 `worktree_identity`（覆盖 `HEAD + staged + unstaged + untracked`）。
+3. 命中 binary：local path pod 从 `Development Pods` 提升为 binary pod。
+4. 未命中 binary：自动回退源码，不阻断依赖分析流程。
+
+### 核心实现入口
+
+| 文件 | 作用 |
+|---|---|
+| `lib/cocoapods-meitu-bin/helpers/worktree_identity.rb` | 计算 `worktree_identity`，提供规则版本和 git/fallback 双路径。 |
+| `lib/cocoapods-meitu-bin/native/resolver.rb` | 在 `resolve` / `resolver_specs_by_target` 阶段执行 source/binary 决策与替换。 |
+| `lib/cocoapods-meitu-bin/helpers/buildAll/bin_helper.rb` | 生成 binary version，优先使用 `worktree_identity`。 |
+| `lib/cocoapods-meitu-bin/config/config.rb` (`PodUpdateConfig`) | 缓存 identity、checkout options、依赖关系、promote 状态。 |
+| `lib/cocoapods-meitu-bin/source_provider_hook.rb` | `source_provider`/`pre_install` 阶段收集 `:path/:commit` 上下文。 |
+
+### `worktree_identity` 生成规则（详细）
+
+规则版本：`v1_git_tree_diff_untracked_sha1`
+
+计算对象：当前一次依赖分析涉及的本地组件目录（通常是 local podspec 所在目录）。
+
+```text
+base_tree_sha   = git rev-parse HEAD:<relative_path>
+staged_diff_sha = sha1(git diff --cached --binary -- <path>)
+unstaged_sha    = sha1(git diff --binary -- <path>)
+untracked_sha   = sha1(untracked_file_list + file_contents)
+
+worktree_identity = sha1(base_tree_sha + "|" + staged_diff_sha + "|" + unstaged_sha + "|" + untracked_sha)
+```
+
+字段解释：
+
+1. `base_tree_sha`：模块在 `HEAD` 下的快照标识（提交态）。
+2. `staged_diff_sha`：已 `git add` 但未提交的改动。
+3. `unstaged_sha`：工作区未暂存改动。
+4. `untracked_sha`：未跟踪文件列表与内容摘要。
 
-### 制作二进制
+为什么必须包含 `unstaged/untracked`：
 
-进入`Podfile`所在目录，执行`pod bin build-all`即可，根据需要添加相应的`option`选项，支持的`option`选项如下：
+1. 只用提交态会误把“本地已改但未提交”组件当成可复用旧 binary。
+2. 新增文件（最常见）如果不纳入 identity，会出现错误命中旧二进制。
+
+回退策略：
+
+1. 若目录不在 git 仓库内，或 git 查询失败，则回退为“目录相对路径 + 文件内容”摘要。
+2. 回退后仍能保证 identity 随文件变化而变化。
+
+### 在依赖分析中的实际执行过程（按时序）
+
+1. `:pre_install` / `:source_provider`：
+   插件加载并收集 Podfile 中 `:path`、`:commit` 等信息，写入 `PodUpdateConfig`。
+2. `Resolver#resolve` 前半段：
+   识别本轮本地 root（`sandbox.development_pods + Podfile external_source[:path]`）。
+3. `Resolver#resolve` 预计算：
+   对本地 root 调用 `WorktreeIdentity.for_sandbox_pod`，把 identity 写入 `PodUpdateConfig`。
+4. `Resolver#resolve` 依赖关系：
+   构建 `dependency_relationships`，给 binary version 计算提供依赖链输入。
+5. `Resolver#resolver_specs_by_target` 决策：
+   对每个 rspec 判定 `use_binary`，并处理 `use_source_pods` / 黑名单 / selector。
+6. binary version 计算：
+   `BinHelper.version` 对 local root 优先取 `worktree_identity`，其次 `commit/tag`，最后才是版本号。
+7. 命中 binary：
+   用 binary source 的 spec 替换 rspec，并执行 `promote_local_path_pod_to_binary`。
+8. 未命中 binary：
+   保留源码 rspec（必要时补 `checkout_source`），自动回退源码流程。
+9. root + subspec 一致性：
+   同一 local root 一旦命中 binary，其余 subspec 强制复用同一 binary version，避免 mixed mode。
+
+### 状态流转（`PodUpdateConfig`）
+
+| 状态 | 含义 | 主要写入点 |
+|---|---|---|
+| `worktree_identities` | root -> identity | `resolve` 预计算与按需补算 |
+| `checkout_options` | root -> git/commit/tag | 解析 checkout options 后写入 |
+| `dependency_relationships` | root -> 依赖身份串 | `resolve` 依赖图构建后写入 |
+| `promoted_local_pods` | 已提升为 binary 的本地 root | `promote_local_path_pod_to_binary` |
+| `external_source_binary` | 壳工程制作时可参与处理的 external 组件 | resolver 记录 |
+
+### Monorepo 动态切换流程图（详细）
+
+```mermaid
+flowchart TD
+    A["pod install"] --> B["pre_install/source_provider 收集 :path/:commit"]
+    B --> C["resolve: 识别本地 root 集合"]
+    C --> D["预计算 worktree_identity 并写入 PodUpdateConfig"]
+    D --> E["构建 dependency_relationships"]
+    E --> F["resolver_specs_by_target 逐 rspec 判定 use_binary"]
+    F --> G{"是否强制源码\\n(use_source_pods / selector / force env)?"}
+    G -->|是| H["保留源码 rspec"]
+    G -->|否| I["BinHelper.version 计算 binary version\\n优先 identity"]
+    I --> J{"binary source 命中?"}
+    J -->|命中| K["替换为 binary spec\\npromote local path pod"]
+    J -->|未命中| L["回退源码\\n保留 external/local source"]
+    H --> M["生成最终 Pods 工程"]
+    K --> M
+    L --> M
+```
+
+## 环境变量与开关
+
+| 变量 | 默认值 | 作用 |
+|---|---|---|
+| `MEITU_USE_BINARIES` | `true`（未设时） | Podfile 层总开关。设为 `false` 可全源码。 |
+| `MEITU_USE_CONFIGURATION` | `Debug` | 指定二进制版本计算和命中所用配置（如 `Debug`/`Release`）。 |
+| `MEITU_FORCE_LOCAL_PATH_SOURCE` | `false` | 兼容旧逻辑。设为 `true` 且 `configuration_env == 'dev'` 时，本地 `:path` 组件强制进源码白名单。 |
+| `MEITU_BIN_WORKTREE_DEBUG` | `0` | 设为 `1` 输出 worktree identity 统计和切换调试日志。 |
+| `MEITU_BIN_BUILD_LOCAL_PATH_PODS` | `true` | 控制 `pod bin build-all` 是否制作本地 `:path` 组件。设为 `false` 回退旧行为（跳过本地库）。 |
+
+## 二进制制作（build-all）
+
+进入 `Podfile` 所在目录执行：
+
+```shell
+pod bin build-all --configuration=Debug
+```
+
+常见参数：
 
 | 选项 | 含义 |
 |---|---|
-| `--clean` | 全部二进制包制作完成后删除编译临时目录 |
-| `--clean-single` | 每制作完一个二进制包就删除该编译临时目录 |
-| `--repo-update` | 更新`Podfile`中指定的`repo`仓库 |
-| `--full-build` | 是否全量编译 |
-| `--skip-simulator` | 是否跳过模拟器编译 |
-| `--configuration=configName` | 在构建每个目标时使用`configName`指定构建配置，如：`Debug`、`Release`等 |
+| `--clean` | 全部制作完成后清理临时目录 |
+| `--clean-single` | 每个组件完成后立刻清理临时目录 |
+| `--repo-update` | 先更新 Podfile 里声明的 source 仓库 |
+| `--full-build` | 强制全量制作（不复用已存在 binary） |
+| `--skip-simulator` | 跳过模拟器架构制作 |
+| `--configuration=configName` | 指定构建配置 |
+| `--shell-project` | 基于壳工程产物执行打包 |
 
-> 如果想查看详细信息，可以使用`pod bin build-all --help`来查看帮助文档
+### build-all 对不同依赖类型的处理
 
-### 使用二进制
+1. 本地 `:path` 组件：默认参与制作。
+2. external source（如 `:git/:commit/:tag`）：
+   在普通 `build-all` 流程中，命中 `sandbox.checkout_sources` 即跳过，不参与制作。
+   在 `--shell-project` 流程中，只有当组件被标记进 `PodUpdateConfig.external_source_binary` 集合时才会参与制作；未命中集合仍跳过。
+   `external_source_binary` 集合由 resolver 阶段记录，目的是给后续壳工程制作场景提供“可制作的 external 组件”输入。
+3. 无源码组件：跳过。
+4. 已存在同版本 binary：跳过。
 
-在`Podfile`中添加如下代码，然后执行`pod install`即可
+## 流程图
 
-```ruby
-# 加载插件
-plugin 'cocoapods-meitu-bin'
-# 开启二进制
-use_binaries!
-# 设置源码白名单
-set_use_source_pods ['AFNetworking']
+### 1) `pod install`：monorepo 本地 path 与二进制动态切换
+
+```mermaid
+flowchart TD
+    A["pod install"] --> B["source_provider / pre_install"]
+    B --> C["resolve 阶段预计算 local path worktree_identity"]
+    C --> D["构建 dependency_relationships"]
+    D --> E["resolver_specs_by_target 按 rspec 决策 source/binary"]
+    E --> F{"是否强制源码\n(MEITU_FORCE_LOCAL_PATH_SOURCE / use_source_pods)?"}
+    F -->|是| G["保留源码（Development Pods）"]
+    F -->|否| H["计算 binary version\n(identity/commit/tag/依赖关系)"]
+    H --> I{"binary spec 是否命中?"}
+    I -->|命中| J["promote local path pod -> binary pod\n移出 Development Pods"]
+    I -->|未命中| K["回退源码（保留 :path / external source）"]
+    G --> L["生成 Pods 工程/Lockfile"]
+    J --> L
+    K --> L
 ```
+
+### 2) `pod bin build-all`：二进制制作流程（含本地 `:path`）
+
+```mermaid
+flowchart TD
+    A["pod bin build-all"] --> B["读取 BinConfig.yaml + CLI 参数"]
+    B --> C["Analyzer 分析 pod_targets"]
+    C --> D["遍历每个 pod_target"]
+    D --> E{"命中黑名单/不在白名单?"}
+    E -->|是| D2["跳过"]
+    E -->|否| F{"本地 :path 且\nMEITU_BIN_BUILD_LOCAL_PATH_PODS=false?"}
+    F -->|是| D2
+    F -->|否| G{"external source 或无源码?"}
+    G -->|是| D2
+    G -->|否| H["计算 binary version"]
+    H --> I{"binary 已存在且非 full-build?"}
+    I -->|是| D2
+    I -->|否| J["编译产物 -> create_binary"]
+    J --> K["zip + upload artifact"]
+    K --> L["生成并 push binary podspec"]
+    L --> M["汇总 Success/Fail 结果"]
+    D2 --> M
+```
+
+## 常用命令
+
+```shell
+# 开启调试日志看切换细节
+MEITU_BIN_WORKTREE_DEBUG=1 pod install
+
+# 强制本地 :path 组件全源码（应急排障，仅在 Podfile 的 configuration_env == 'dev' 时生效）
+MEITU_FORCE_LOCAL_PATH_SOURCE=true pod install
+
+# 本地 :path 组件也参与制作（默认就是 true）
+MEITU_BIN_BUILD_LOCAL_PATH_PODS=true pod bin build-all --configuration=Debug
+
+# 回退旧行为：build-all 跳过本地 :path
+MEITU_BIN_BUILD_LOCAL_PATH_PODS=false pod bin build-all --configuration=Debug
+```
+
+## 排障建议
+
+1. 切换不生效：先开 `MEITU_BIN_WORKTREE_DEBUG=1`，看 `resolved/missing` 与 `forced_source` 统计。
+2. 命中旧 binary：检查是否有未跟踪文件变化、`set_use_source_pods` 白名单、`MEITU_FORCE_LOCAL_PATH_SOURCE`。
+3. binary 存在但安装失败：检查 binary spec 与 artifact 是否同时可访问。
+4. 本地库制作被跳过：检查 `MEITU_BIN_BUILD_LOCAL_PATH_PODS` 是否被设为 `false`。
+
+## 参考
+
+- [美图秀秀 iOS 客户端二进制之路](https://juejin.cn/post/7175023366783385659)

data/lib/cocoapods-meitu-bin/command/bin/build_all.rb

@@ -49,6 +49,7 @@ module Pod
           @configuration = argv.option('configuration', 'Debug')
           @base_dir = ENV['POD_BUILD_BASE_DIR'] || "#{Pathname.pwd}/all_build/Build"
           @version_helper = BinHelper.new
+          @subspec_root_payload_white_list = []
           super
         end
 
@@ -117,7 +118,9 @@ module Pod
             @post_build = build_config['post_build']
             @black_list = build_config['black_list']
             @write_list = build_config['write_list']
+            @subspec_root_payload_white_list = Array(build_config['subspec_root_payload_white_list']).compact
             UI.info "BinConfig：`#{@write_list}`".yellow
+            UI.info "BinConfig subspec_root_payload_white_list：`#{@subspec_root_payload_white_list}`".yellow
           end
         end
 
@@ -211,19 +214,18 @@ module Pod
             created_pods = []
             pod_targets.map do |pod_target|
               begin
-                version = @version_helper.version(pod_target.pod_name, pod_target.root_spec.version.to_s, @analyze_result.specifications, @configuration, podfile.include_dependencies?)
                 # 黑名单（不分全量和非全量）
                 next if skip_build?(pod_target)
                 # 白名单（有白名单，只看白名单，不分全量和非全量）
-                UI.info "USE_WHITELIST：`#{ ENV['USE_WHITELIST']}`".yellow
-                UI.info "include?：`#{@write_list.include?(pod_target.pod_name)}`".yellow
                 next if ENV['USE_WHITELIST'] && !@write_list.nil? && !@write_list.empty? && !@write_list.include?(pod_target.pod_name)
-                # 本地库
-                if @sandbox.local?(pod_target.pod_name)
+                local_pod = @sandbox.local?(pod_target.pod_name)
+                if local_pod && !build_local_path_pods?
                   local_pods << pod_target.pod_name
-                  show_skip_tip("#{pod_target.pod_name} 是本地库")
+                  show_skip_tip("#{pod_target.pod_name} 是本地库（MEITU_BIN_BUILD_LOCAL_PATH_PODS=false，跳过制作）")
                   next
                 end
+                # 默认将 :path 组件纳入 build-all，和 resolver 的动态切换保持同一套版本语义。
+                show_build_tip("#{pod_target.pod_name} 是本地库，将参与二进制制作") if local_pod
                 # 外部源（如 git）
                 if @sandbox.checkout_sources[pod_target.pod_name]
                   external_pods << pod_target.pod_name
@@ -236,9 +238,11 @@ module Pod
                   show_skip_tip("#{pod_target.pod_name} 无需编译")
                   next
                 end
+                version = @version_helper.version(pod_target.pod_name, pod_target.root_spec.version.to_s, @analyze_result.specifications, @configuration, podfile.include_dependencies?)
                 # 非全量编译、不在白名单中且已经有相应的二进制版本
                 if has_created_binary?(pod_target.pod_name, version)
                   created_pods << pod_target.pod_name
+                  # 版本命中后直接复用已有 binary，避免重复构建上传。
                   show_skip_tip("#{pod_target.pod_name}(#{version}) 已经有二进制版本了")
                   next
                 end
@@ -257,7 +261,13 @@ module Pod
                 fail_pods << pod_target.pod_name unless result
                 next unless result
                 # 生成二进制podspec并上传
-                podspec_creator = PodspecUtil.new(pod_target, version, builder.build_as_framework?, @configuration)
+                podspec_creator = PodspecUtil.new(
+                  pod_target,
+                  version,
+                  builder.build_as_framework?,
+                  @configuration,
+                  subspec_root_payload_white_list: @subspec_root_payload_white_list
+                )
                 bin_spec = podspec_creator.create_binary_podspec
                 bin_spec_file = podspec_creator.write_binary_podspec(bin_spec)
                 result = podspec_creator.push_binary_podspec(bin_spec_file)
@@ -280,7 +290,8 @@ module Pod
               'No Source File' => binary_pods,
               'Created Binary' => created_pods,
               'Black List' => @black_list || [],
-              'Write List' => @write_list || []
+              'Write List' => @write_list || [],
+              'Subspec Root Payload White List' => @subspec_root_payload_white_list || []
             }
             show_results(results)
             results
@@ -302,24 +313,25 @@ module Pod
             # mutex = Mutex.new
             pod_targets.map do |pod_target|
               begin
-                version = @version_helper.version(pod_target.pod_name, pod_target.root_spec.version.to_s, @analyze_result.specifications, @configuration, podfile.include_dependencies?)
                 # 黑名单（不分全量和非全量）
                 next if skip_build?(pod_target)
                 # 白名单（有白名单，只看白名单，不分全量和非全量）
                 next if ENV['USE_WHITELIST'] && !@write_list.nil? && !@write_list.empty? && !@write_list.include?(pod_target.pod_name)
-                # 本地库
-                if @sandbox.local?(pod_target.pod_name)
+                local_pod = @sandbox.local?(pod_target.pod_name)
+                if local_pod && !build_local_path_pods?
                   local_pods << pod_target.pod_name
-                  show_skip_tip("#{pod_target.pod_name} 是本地库")
+                  show_skip_tip("#{pod_target.pod_name} 是本地库（MEITU_BIN_BUILD_LOCAL_PATH_PODS=false，跳过制作）")
                   next
                 end
+                # shell-project 模式下同样遵循本地 :path 组件默认参与制作的策略。
+                show_build_tip("#{pod_target.pod_name} 是本地库，将参与二进制制作") if local_pod
                 # 外部源（如 git）
                 excluded_names = PodUpdateConfig.external_source_binary
-                                                .map { |s| s[:name] }
+                                                .map { |s| s[:name] || s['name'] }
                                                 .compact # 过滤nil值
                                                 .uniq   # 去重
 
-                if @sandbox.checkout_sources[pod_target.pod_name] && !excluded_names.include?(pod_target.pod_name) && !pod_target.should_build?
+                if excluded_names.include?(pod_target.pod_name) || (@sandbox.checkout_sources[pod_target.pod_name] && !pod_target.should_build?)
                   external_pods << pod_target.pod_name
                   show_skip_tip("#{pod_target.pod_name} 以external方式引入")
                   next
@@ -330,6 +342,7 @@ module Pod
                   show_skip_tip("#{pod_target.pod_name} 无需编译")
                   next
                 end
+                version = @version_helper.version(pod_target.pod_name, pod_target.root_spec.version.to_s, @analyze_result.specifications, @configuration, podfile.include_dependencies?)
                 # 非全量编译、不在白名单中且已经有相应的二进制版本
                 if has_created_binary?(pod_target.pod_name, version)
                   created_pods << pod_target.pod_name
@@ -383,7 +396,13 @@ module Pod
                 fail_pods << pod_target.pod_name unless result
                 next unless result
                 # 生成二进制podspec并上传
-                podspec_creator = PodspecUtil.new(pod_target, version, builder.build_as_framework?, @configuration)
+                podspec_creator = PodspecUtil.new(
+                  pod_target,
+                  version,
+                  builder.build_as_framework?,
+                  @configuration,
+                  subspec_root_payload_white_list: @subspec_root_payload_white_list
+                )
                 bin_spec = podspec_creator.create_binary_podspec
                 bin_spec_file = podspec_creator.write_binary_podspec(bin_spec)
                 result = podspec_creator.push_binary_podspec(bin_spec_file)
@@ -407,7 +426,8 @@ module Pod
               'No Source File' => binary_pods,
               'Created Binary' => created_pods,
               'Black List' => @black_list || [],
-              'Write List' => @write_list || []
+              'Write List' => @write_list || [],
+              'Subspec Root Payload White List' => @subspec_root_payload_white_list || []
             }
 
             show_results(results)
@@ -419,11 +439,21 @@ module Pod
           UI.info title.yellow
         end
 
+        def show_build_tip(title)
+          UI.info title.green
+        end
+
         # 是否跳过编译
         def skip_build?(pod_target)
           !@black_list.nil? && !@black_list.empty? && @black_list.include?(pod_target.pod_name)
         end
 
+        # 本地 :path 组件是否参与 build-all 二进制制作
+        # 默认开启；设置 MEITU_BIN_BUILD_LOCAL_PATH_PODS=false 可回退旧行为（本地库跳过）
+        def build_local_path_pods?
+          ENV['MEITU_BIN_BUILD_LOCAL_PATH_PODS'] != 'false'
+        end
+
         # 展示结果
         def show_results(results)
           UI.title '打包结果：'.green do

data/lib/cocoapods-meitu-bin/config/config.rb

@@ -178,6 +178,10 @@ class PodUpdateConfig
   # 记录 Podfile 中通过 :commit 指定的本地组件及其 git 信息,格式: { pod_name => { git: git_url, commit: commit_hash } }
   # mbox 激活组件，避免关联组件都切换到源码，影响编译速度
   @@pods_with_commit = {}
+  # local path 组件在当前一次 resolve 中的身份快照（root_name => worktree_identity）
+  @@worktree_identities = {}
+  # 已从 Development Pods 提升为 binary 的 local path 组件（用于去重和调试）
+  @@promoted_local_pods = {}
 
   # 设置依赖关系集合
   def self.set_dependency_relationships(relationships)
@@ -230,6 +234,33 @@ class PodUpdateConfig
 
   end
 
+  def self.set_worktree_identity(pod_name, identity)
+    return if identity.nil? || identity.empty?
+
+    @@worktree_identities[Pod::Specification.root_name(pod_name)] = identity
+  end
+
+  def self.get_worktree_identity(pod_name)
+    @@worktree_identities[Pod::Specification.root_name(pod_name)]
+  end
+
+  def self.worktree_identities
+    @@worktree_identities
+  end
+
+  def self.promote_local_pod(pod_name, metadata = {})
+    # metadata 默认包含命中的 binary version 与 identity，便于后续日志/排障追踪。
+    @@promoted_local_pods[Pod::Specification.root_name(pod_name)] = metadata
+  end
+
+  def self.promoted_local_pod?(pod_name)
+    @@promoted_local_pods.key?(Pod::Specification.root_name(pod_name))
+  end
+
+  def self.promoted_local_pods
+    @@promoted_local_pods
+  end
+
   def self.set_external_source_binary(dic)
     @@external_source_binary << dic
   end
@@ -400,16 +431,12 @@ class PodUpdateConfig
     @@pods = []
     @@lockfile = nil
     @@is_clear = true
+    @@worktree_identities = {}
+    @@promoted_local_pods = {}
   end
   def self.is_clear
     @@is_clear
   end
-
-  def self.clear
-    @@pods = []
-    @@lockfile = nil
-    @@is_clear = true
-  end
   def self.is_podfile_lock_nil
     @@is_podfile_lock_nil
   end

data/lib/cocoapods-meitu-bin/gem_version.rb

@@ -1,5 +1,5 @@
 module CBin
-  VERSION = "3.0.2"
+  VERSION = "3.0.3"
 end
 
 module Pod

data/lib/cocoapods-meitu-bin/helpers/buildAll/bin_helper.rb

@@ -21,7 +21,12 @@ module CBin
           # 将当前 pod 自身的 commit/tag 加入版本号计算字符串
           # 修复：Podfile 中通过 :commit/:tag 指定的 pod，其自身 commit 信息必须参与 MD5 计算
           # 否则更新 Podfile 的 commit 后版本号不变，会错误命中旧的二进制缓存
-          self_checkout = PodUpdateConfig.get_checkout_option(pod_name)
+          self_checkout = PodUpdateConfig.get_worktree_identity(pod_name)
+          if ENV['MEITU_BIN_WORKTREE_DEBUG'] == '1' && self_checkout
+            UI.puts "#{pod_name} worktree_identity：#{self_checkout}".yellow
+          end
+
+          self_checkout ||= PodUpdateConfig.get_checkout_option(pod_name)
           self_checkout ||= PodUpdateConfig.get_with_commit(pod_name)
           specs << "#{pod_name}(#{self_checkout})" if self_checkout
 
@@ -67,6 +72,13 @@ module CBin
         return '' if all_dependencies.nil? || all_dependencies.empty?
         result = []
         all_dependencies.each do |pod_name|
+          worktree_identity = PodUpdateConfig.get_worktree_identity(pod_name)
+          if worktree_identity
+            # local :path 组件优先采用 worktree identity，避免仅靠 commit/tag 导致命中旧缓存。
+            result << "#{pod_name}(#{worktree_identity})"
+            next
+          end
+
           # 优先使用 get_checkout_option 中的 commit 或 tag
           checkout_option = PodUpdateConfig.get_checkout_option(pod_name)
           if checkout_option

data/lib/cocoapods-meitu-bin/helpers/buildAll/podspec_util.rb

@@ -4,11 +4,12 @@ module CBin
     class PodspecUtil
       include Pod
 
-      def initialize(pod_target, version, build_as_framework = false, configuration = 'Debug')
+      def initialize(pod_target, version, build_as_framework = false, configuration = 'Debug', options = {})
         @pod_target = pod_target
         @version = version
         @build_as_framework = build_as_framework
         @configuration = configuration
+        @subspec_root_payload_white_list = Array(options[:subspec_root_payload_white_list]).compact
       end
 
       # 创建二进制podspec
@@ -93,9 +94,9 @@ module CBin
       private
 
       # 删除无用的字段
-      def delete_unused(spec)
+      def delete_unused(spec, keep_resource_bundles: false)
         spec.delete('project_header_files')
-        spec.delete('resource_bundles')
+        spec.delete('resource_bundles') unless keep_resource_bundles
         spec.delete('exclude_files')
         spec.delete('preserve_paths')
         spec.delete('prepare_command')
@@ -103,35 +104,51 @@ module CBin
 
       # 处理subspecs
       def handle_subspecs(spec)
+        root_payload_only = subspec_root_payload_only?
+        if root_payload_only
+          UI.info "PodspecUtil：`#{@pod_target.pod_name}` 命中 subspec_root_payload_white_list，subspec 不复制 vendored/resources".yellow
+        end
         spec['subspecs'].map do |subspec|
           # 处理单个subspec
-          handle_single_subspec(subspec, spec)
+          handle_single_subspec(subspec, spec, root_payload_only)
           # 递归处理subspec
-          recursive_handle_subspecs(subspec['subspecs'], spec)
+          recursive_handle_subspecs(subspec['subspecs'], spec, root_payload_only)
         end if spec && spec['subspecs']
       end
 
       # 递归处理subspecs
-      def recursive_handle_subspecs(subspecs, spec)
+      def recursive_handle_subspecs(subspecs, spec, root_payload_only)
         subspecs.map do |s|
           # 处理单个subspec
-          handle_single_subspec(s, spec)
+          handle_single_subspec(s, spec, root_payload_only)
           # 递归处理
-          recursive_handle_subspecs(s['subspecs'], spec)
+          recursive_handle_subspecs(s['subspecs'], spec, root_payload_only)
         end if subspecs
       end
 
       # 处理单个subspec
-      def handle_single_subspec(subspec, spec)
+      def handle_single_subspec(subspec, spec, root_payload_only)
         subspec['source_files'] = spec['source_files']
         subspec['public_header_files'] = spec['public_header_files']
         subspec['private_header_files'] = spec['private_header_files']
-        subspec['vendored_frameworks'] = spec['vendored_frameworks']
-        subspec['vendored_libraries'] = spec['vendored_libraries']
-        subspec['resources'] = spec['resources']
+        if root_payload_only
+          # 仅 root 声明二进制 payload，避免 subspec 重复嵌入同名 framework
+          subspec.delete('vendored_frameworks')
+          subspec.delete('vendored_libraries')
+          subspec.delete('resources')
+          subspec.delete('resource_bundles')
+        else
+          subspec['vendored_frameworks'] = spec['vendored_frameworks']
+          subspec['vendored_libraries'] = spec['vendored_libraries']
+          subspec['resources'] = spec['resources']
+        end
         # 删除无用字段
         subspec.delete('source')
-        delete_unused(subspec)
+        delete_unused(subspec, keep_resource_bundles: !root_payload_only)
+      end
+
+      def subspec_root_payload_only?
+        @subspec_root_payload_white_list.include?(@pod_target.pod_name)
       end
 
       def source

data/lib/cocoapods-meitu-bin/helpers/worktree_identity.rb

@@ -0,0 +1,93 @@
+require 'digest'
+require 'find'
+require 'open3'
+require 'pathname'
+
+module CBin
+  module Helpers
+    module WorktreeIdentity
+      module_function
+      # 规则版本会进入调试日志，便于在不同实现版本间快速对齐排障。
+      RULE_VERSION = 'v1_git_tree_diff_untracked_sha1'.freeze
+
+      def rule_version
+        RULE_VERSION
+      end
+
+      def for_sandbox_pod(sandbox, pod_name)
+        podspec_path = sandbox.local_podspec(pod_name)
+        return nil unless podspec_path
+
+        # local podspec 所在目录即该组件在 monorepo 中的实际模块目录。
+        compute(Pathname.new(podspec_path).dirname)
+      end
+
+      def compute(module_dir)
+        module_dir = Pathname.new(module_dir).expand_path
+        git_root = git_output(module_dir.to_s, %w[rev-parse --show-toplevel])
+        return fallback_directory_digest(module_dir) if git_root.nil? || git_root.empty?
+
+        git_root_path = Pathname.new(git_root)
+        relative_path = module_dir.relative_path_from(git_root_path).to_s
+        # 四段输入覆盖 HEAD/index/worktree/untracked：
+        # 1) base_tree: HEAD 下模块快照
+        # 2) staged_diff: 已暂存改动
+        # 3) unstaged_diff: 未暂存改动
+        # 4) untracked_digest: 未跟踪文件列表 + 内容
+        base_tree = git_output(git_root, ['rev-parse', "HEAD:#{relative_path}"], allow_failure: true).to_s
+        staged_diff = git_output(git_root, ['diff', '--cached', '--binary', '--no-ext-diff', '--', relative_path], allow_failure: true).to_s
+        unstaged_diff = git_output(git_root, ['diff', '--binary', '--no-ext-diff', '--', relative_path], allow_failure: true).to_s
+        untracked_lines = git_output(git_root, ['ls-files', '--others', '--exclude-standard', '--', relative_path], allow_failure: true).to_s
+
+        untracked_digest = Digest::SHA1.new
+        untracked_lines.lines.map(&:chomp).reject(&:empty?).sort.each do |entry|
+          abs_path = git_root_path.join(entry)
+          untracked_digest.update(entry)
+          untracked_digest.update("\0")
+          untracked_digest.file(abs_path.to_s) if abs_path.file?
+          untracked_digest.update("\0")
+        end
+
+        payload = [
+          base_tree,
+          Digest::SHA1.hexdigest(staged_diff),
+          Digest::SHA1.hexdigest(unstaged_diff),
+          untracked_digest.hexdigest,
+        ].join('|')
+
+        Digest::SHA1.hexdigest(payload)
+      rescue ArgumentError, Errno::ENOENT
+        # Git 查询异常时回退到全目录摘要，确保仍有稳定 identity 可用于版本计算。
+        fallback_directory_digest(module_dir)
+      end
+
+      def git_output(chdir, args, allow_failure: false)
+        stdout, status = Open3.capture2('git', *args, chdir: chdir)
+        return stdout.strip if status.success?
+        # allow_failure 为 true 的场景用于容忍“模块首次接入/路径不存在于 HEAD”等可预期情况。
+        return nil if allow_failure
+
+        nil
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def fallback_directory_digest(module_dir)
+        digest = Digest::SHA1.new
+
+        # 非 git 场景：按相对路径 + 文件内容做摘要，保证目录态变化可感知。
+        Find.find(module_dir.to_s) do |path|
+          next if File.directory?(path)
+
+          rel_path = Pathname.new(path).relative_path_from(module_dir).to_s
+          digest.update(rel_path)
+          digest.update("\0")
+          digest.file(path)
+          digest.update("\0")
+        end
+
+        digest.hexdigest
+      end
+    end
+  end
+end

data/lib/cocoapods-meitu-bin/native/installer.rb

@@ -80,7 +80,7 @@ module Pod
       UI.section 'Analyzing dependencies' do
         analyze(analyzer)
         excluded_names = PodUpdateConfig.external_source
-                                        .map { |s| s[:name] }
+                                        .map { |s| s[:name] || s['name'] }
                                         .compact
                                         .uniq
 

data/lib/cocoapods-meitu-bin/native/lockfile.rb

@@ -73,7 +73,7 @@ module Pod
       #根据 CocoaPods 依赖处理机制，修改后的方法应增加过滤逻辑：
       def generate_external_sources_data(podfile)
         excluded_names = PodUpdateConfig.external_source
-                    .map { |s| s[:name] }
+                    .map { |s| s[:name] || s['name'] }
                     .compact # 过滤nil值
                     .uniq   # 去重
                     

data/lib/cocoapods-meitu-bin/native/resolver.rb

@@ -6,6 +6,7 @@ require 'cocoapods-meitu-bin/native/installation_options'
 require 'cocoapods-meitu-bin/gem_version'
 # require 'cocoapods-meitu-bin/command/bin/archive'
 require 'cocoapods-meitu-bin/helpers/buildAll/bin_helper'
+require 'cocoapods-meitu-bin/helpers/worktree_identity'
 require 'cocoapods-meitu-bin/config/config'
 
 module Pod
@@ -150,16 +151,24 @@ module Pod
 
 
         if podfile.use_binaries?
+          # 预计算 local path 组件 identity，避免在 rspec 循环里重复扫描目录。
           path_pods = @podfile_dependency_cache.podfile_dependencies
                                                .select { |dep| dep.external_source && dep.external_source[:path] }
                                                .map(&:root_name)
                                                .uniq
+          local_pods = (sandbox.development_pods.keys + path_pods)
+                         .map { |name| Pod::Specification.root_name(name) }
+                         .uniq
           path_commit_pods = {}
-          path_pods.each do |pod_name|
+          local_pods.each do |pod_name|
+            worktree_identity = CBin::Helpers::WorktreeIdentity.for_sandbox_pod(sandbox, pod_name)
+            PodUpdateConfig.set_worktree_identity(pod_name, worktree_identity) if worktree_identity
             if PodUpdateConfig.pods_with_commit[pod_name]
+              # :path + :commit 的组件继续保留 commit 输入，避免 identity 缺失时版本退化。
               path_commit_pods[pod_name] = PodUpdateConfig.pods_with_commit[pod_name]
             end
           end
+          print_worktree_identity_debug(local_pods, 'after_precompute')
           PodUpdateConfig.parse_checkout_options_from_specs(checkout_options,podfile,path_commit_pods)
         end
 
@@ -238,8 +247,12 @@ module Pod
               # end
             else
               name_version = "#{pod_name}_#{dep_info[:version].version}"
+              worktree_identity = PodUpdateConfig.get_worktree_identity(pod_name)
               opts = path_commit_pods&.[](pod_name)
-              if opts && opts[:commit]
+              if worktree_identity
+                name_worktree = "#{pod_name}_#{worktree_identity}"
+                pod_names << name_worktree unless pod_names.join("|").include?(pod_name)
+              elsif opts && opts[:commit]
                 commit = opts[:commit]
                 name_commit = "#{pod_name}_#{commit}"
                 pod_names << name_commit unless pod_names.join("|").include?(pod_name)
@@ -278,14 +291,29 @@ module Pod
 
         sources_manager = Config.instance.sources_manager
         use_source_pods = podfile.use_source_pods
+        use_source_roots = use_source_pods.map { |name| Pod::Specification.root_name(name) }.uniq
 
         # 从BinConfig读取black_list
         black_list = read_black_list
         use_source_pods.concat(black_list).uniq! unless black_list.nil?
+        use_source_roots = use_source_pods.map { |name| Pod::Specification.root_name(name) }.uniq
+        if podfile.use_binaries? && ENV['MEITU_BIN_WORKTREE_DEBUG'] == '1'
+          local_path_roots = sandbox.development_pods.keys.map { |name| Pod::Specification.root_name(name) }.uniq
+          forced_source_roots = local_path_roots & use_source_roots
+          candidate_binary_roots = local_path_roots - forced_source_roots
+          UI.puts "worktree_identity_debug(use_source): local_path=#{local_path_roots.size}, forced_source=#{forced_source_roots.size}, binary_candidates=#{candidate_binary_roots.size}".yellow
+          unless forced_source_roots.empty?
+            UI.puts "worktree_identity_debug(forced_source_local): #{forced_source_roots.sort.join(',')}".yellow
+          end
+        end
 
         specifications = specs_by_target.values.flatten.map(&:spec).uniq
 
         missing_binary_specs = []
+        # 注意这里取快照：后续 promote_local_path_pod_to_binary 会改 sandbox.local? 状态。
+        local_path_roots_snapshot = sandbox.development_pods.keys.map { |name| Pod::Specification.root_name(name) }.uniq
+        binary_version_by_local_root = {}
+        local_root_binary_state = {}
         specs_by_target.each do |target, rspecs|
           # use_binaries 并且 use_source_pods 不包含  本地可过滤
           use_binary_rspecs = if podfile.use_binaries? || podfile.use_binaries_selector
@@ -305,30 +333,52 @@ module Pod
 
             # developments 组件采用默认输入的 spec (development pods 的 source 为 nil)
             # 可以使 :podspec => "htts://IMYFoundation.podspec"可以走下去，by slj
-            dependency_source = PodUpdateConfig.get_checkout_option(rspec.root.name)
+            root_name = Pod::Specification.root_name(rspec.root.name)
+            dependency_source = PodUpdateConfig.get_checkout_option(root_name)
+            # 注意：本轮中会调用 promote_local_path_pod_to_binary 修改 sandbox.local? 状态，
+            # 这里使用快照保证同一 root 的 root+subspec 判定一致，避免 mixed mode。
+            is_local_path_pod = local_path_roots_snapshot.include?(root_name)
+            local_root_state = if is_local_path_pod
+                                 local_root_binary_state[root_name] ||= { all_binary_hits: true, spec_version: nil }
+                               end
+            if is_local_path_pod && PodUpdateConfig.get_worktree_identity(rspec.root.name).nil?
+              worktree_identity = CBin::Helpers::WorktreeIdentity.for_sandbox_pod(sandbox, rspec.root.name)
+              PodUpdateConfig.set_worktree_identity(rspec.root.name, worktree_identity) if worktree_identity
+            end
 
             # 关键修复：本地 path 依赖的组件（sandbox.local? 为 true）
             # 应该直接使用原始 rspec，不应走 spec repo 查找和替换逻辑
             # 否则如果 spec repo 中的旧版 podspec 缺少某些 subspecs，
             # subspec_by_name 会返回 nil，导致该 subspec 丢失
-            if sandbox.local?(rspec.root.name)
+            if is_local_path_pod && !use_binary_rspecs.include?(rspec)
+              local_root_state[:all_binary_hits] = false if local_root_state
               next rspec
             end
 
             unless rspec.spec.respond_to?(:spec_source) && rspec.spec.spec_source
 
-              if dependency_source.nil?
+              if dependency_source.nil? && !is_local_path_pod
                 next rspec
               end
             end
 
             # 采用二进制依赖并且不为开发组件
             use_binary = use_binary_rspecs.include?(rspec)
+            if !use_binary && binary_version_by_local_root[root_name]
+              # 同一 local root 已命中 binary 时，其余 subspec 也强制复用同一 binary version
+              # 避免 root 与 subspec 混合 source/binary 造成 Swift module/header 不一致。
+              use_binary = true
+            end
             
             if use_binary
               source = sources_manager.binary_source
-              configuration = ENV['configuration'] || podfile.configuration
-              spec_version = version_helper.version(rspec.root.name,  rspec.spec.version, specifications, configuration, podfile.include_dependencies?)
+              spec_version = binary_version_by_local_root[root_name]
+              if spec_version.nil?
+                configuration = ENV['configuration'] || podfile.configuration
+                spec_version = version_helper.version(rspec.root.name, rspec.spec.version, specifications, configuration, podfile.include_dependencies?)
+                binary_version_by_local_root[root_name] = spec_version if is_local_path_pod
+              end
+              local_root_state[:spec_version] ||= spec_version if local_root_state
             else
               # 关键修复：对于通过 commit/tag 指定的组件，在切换到源码时
               # 应该保持原始 rspec，让 CocoaPods 走正常的 external source 下载流程
@@ -368,6 +418,10 @@ module Pod
 
               # 这里可能出现分析依赖的 source 和切换后的 source 对应 specification 的 subspec 对应不上
               # 造成 subspec_by_name 返回 nil，这个是正常现象
+              if specification.nil? && is_local_path_pod && use_binary && local_root_state
+                local_root_state[:all_binary_hits] = false
+                binary_version_by_local_root.delete(root_name)
+              end
               next unless specification
               is_exist_binary_version = true
               used_by_only = if Pod.match_version?('~> 1.7')
@@ -386,6 +440,9 @@ module Pod
               # 没有从新的 source 找到对应版本组件
               missing_binary_specs << rspec.spec if use_binary
               is_exist_binary_version = false
+              # 同一 local root 若某个 subspec 未命中，需要回退该 root 的 binary 版本缓存。
+              binary_version_by_local_root.delete(root_name) if is_local_path_pod
+              local_root_state[:all_binary_hits] = false if is_local_path_pod && use_binary && local_root_state
               
               # 关键修复：对于有 commit/tag 指定的组件，二进制不存在时：
               # 1. 将完整的 checkout_options 添加到 sandbox.checkout_sources
@@ -420,18 +477,29 @@ module Pod
             end
             # 有对应二进制组件版本才进行替换记录，否则走之前pre-downloading 逻辑
             if is_exist_binary_version && sandbox.predownloaded?(rspec.root.name) && spec_version.is_a?(String) && spec_version.include?("bin")
-              PodUpdateConfig.set_external_source({"name":rspec.root.name,"source":dependency_source})
+              PodUpdateConfig.set_external_source({ name: rspec.root.name, source: dependency_source })
             end
             if $ARGV.include?("bin") || !is_exist_binary_version
               # 记录为制作的 external_source 组件，为后续二进制制作准备
               if dependency_source && spec_version.is_a?(String) && spec_version.include?("bin")
-                PodUpdateConfig.set_external_source_binary({"name":rspec.root.name,"source":dependency_source})
+                PodUpdateConfig.set_external_source_binary({ name: rspec.root.name, source: dependency_source })
               end
             end
 
             rspec
           end.compact
         end
+        local_root_binary_state.each do |root_name, state|
+          next unless state[:all_binary_hits]
+          next unless state[:spec_version]
+
+          # 本地 :path 仅在同一 root 的 binary 解析全部成功后，统一提升为普通 binary pod。
+          promote_local_path_pod_to_binary(root_name, state[:spec_version])
+        end
+        if podfile.use_binaries?
+          local_roots = specs_by_target.values.flatten.map { |rs| Pod::Specification.root_name(rs.root.name) }.uniq.select { |name| sandbox.local?(name) }
+          print_worktree_identity_debug(local_roots, 'after_resolver_specs')
+        end
 
         def print_dependency_tree(vertex, indent = 0)
           puts "#{'  ' * indent}#{vertex.name} (#{vertex.payload&.version || '?'})"
@@ -480,6 +548,34 @@ module Pod
                           end
     end
 
+    def print_worktree_identity_debug(local_pods, stage)
+      return unless ENV['MEITU_BIN_WORKTREE_DEBUG'] == '1'
+
+      roots = local_pods.map { |name| Pod::Specification.root_name(name) }.uniq.sort
+      missing = roots.reject { |name| PodUpdateConfig.get_worktree_identity(name) }
+      if stage == 'after_precompute'
+        UI.puts "worktree_identity_debug(rule): #{CBin::Helpers::WorktreeIdentity.rule_version}".yellow
+      end
+      UI.puts "worktree_identity_debug(#{stage}): local=#{roots.size}, resolved=#{roots.size - missing.size}, missing=#{missing.size}".yellow
+      unless missing.empty?
+        UI.puts "worktree_identity_debug_missing(#{stage}): #{missing.join(',')}".yellow
+      end
+    end
+
+    def promote_local_path_pod_to_binary(pod_name, spec_version)
+      root_name = Pod::Specification.root_name(pod_name)
+      return if PodUpdateConfig.promoted_local_pod?(root_name)
+
+      # 提升后的 root 不再视为本地 development pod，后续安装流程将按 binary pod 处理。
+      PodUpdateConfig.promote_local_pod(root_name, {
+        version: spec_version,
+        identity: PodUpdateConfig.get_worktree_identity(root_name),
+      })
+      PodUpdateConfig.set_external_source({ name: root_name, source: { promoted_from: 'path' } })
+      sandbox.development_pods.delete(root_name)
+      sandbox.remove_local_podspec(root_name) if sandbox.respond_to?(:remove_local_podspec)
+    end
+
     # 获取组件的所有依赖(包括直接和间接依赖)
     def get_all_dependencies(vertex, visited = Set.new, dependencies = {})
       return dependencies if vertex.nil? || visited.include?(vertex.name)

data/lib/cocoapods-meitu-bin/source_provider_hook.rb

@@ -221,8 +221,10 @@ Pod::HooksManager.register('cocoapods-meitu-bin', :pre_install) do |_context|
   end
   # get_podfile_lock
 
-  # 有插件/本地库 且是dev环境下，默认进入源码白名单  过滤 archive命令
-  if _context.podfile.plugins.keys.include?('cocoapods-meitu-bin') && _context.podfile.configuration_env == 'dev'
+  # 兼容旧逻辑：dev 环境下将 :path 组件自动加入源码白名单
+  # 默认关闭，避免阻断动态二进制切换。
+  force_local_path_source = ENV['MEITU_FORCE_LOCAL_PATH_SOURCE'] == 'true'
+  if force_local_path_source && _context.podfile.plugins.keys.include?('cocoapods-meitu-bin') && _context.podfile.configuration_env == 'dev'
     dependencies = _context.podfile.dependencies
     dependencies.each do |d|
       next unless d.respond_to?(:external_source) &&
@@ -231,7 +233,7 @@ Pod::HooksManager.register('cocoapods-meitu-bin', :pre_install) do |_context|
                   $ARGV[1] != 'archive'
       _context.podfile.set_use_source_pods d.name
     end
-
+    Pod::UI.puts "MEITU_FORCE_LOCAL_PATH_SOURCE=true: local :path pods forced to source".yellow if ENV['MEITU_BIN_WORKTREE_DEBUG'] == '1'
   end
   PodUpdateConfig.set_prepare_time(Time.now - start_time)
   # 同步 BinPodfile 文件
@@ -269,30 +271,27 @@ Pod::HooksManager.register('cocoapods-meitu-bin', :source_provider) do |context,
   sources_manager = Pod::Config.instance.sources_manager
   podfile = Pod::Config.instance.podfile
 
-  podfile_path = podfile.defined_in_file
   pods_with_commit = {}
   pods_with_path = 0
-  File.readlines(podfile_path).each_with_index do |line, index|
-    # 去除行首空白后检查是否为注释行
-    trimmed_line = line.lstrip
-    next if trimmed_line.start_with?('#')
+  # source_provider 阶段直接使用 Podfile 解析结果：
+  # 1) 收集 external_source 中的 :commit 信息，参与后续 binary version 输入
+  # 2) 统计 :path 数量，辅助决定是否规避 lockfile 缓存
+  podfile.dependencies.each do |dependency|
+    source = dependency.respond_to?(:external_source) ? dependency.external_source : nil
+    next unless source.is_a?(Hash)
 
-    if line.include?(':commit =>')
-      # 提取 pod 名称
-      if line =~ /pod\s+['"]([^'"]+)['"]/
-        pod_name = $1
-        # 提取 commit hash
-        if line =~ /:commit\s*=>\s*['"]([^'"]+)['"]/
-          commit_hash = $1
-          pods_with_commit[pod_name] = { commit: commit_hash }
-        end
-      end
-    elsif line.include?(':path =>')
-      pods_with_path = pods_with_path + 1
+    normalized_source = source.each_with_object({}) do |(key, value), memo|
+      memo[key.to_sym] = value
     end
+
+    root_name = Pod::Specification.root_name(dependency.name)
+    commit_hash = normalized_source[:commit]
+    pods_with_commit[root_name] = { commit: commit_hash } if commit_hash
+    pods_with_path += 1 if normalized_source[:path]
   end
   # 解决多个组件切换从二进制切换到源码受podfile.lock 缓存影响导致切换异常的问题
   if pods_with_path > 2
+    # :path 组件较多时，强制触发重新分析，避免沿用旧 lockfile 造成切换不一致。
     PodUpdateConfig.set_is_podfile_lock_nil(true)
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocoapods-meitu-bin
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.3
 platform: ruby
 authors:
 - Jensen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel
@@ -140,6 +140,7 @@ files:
 - lib/cocoapods-meitu-bin/helpers/spec_files_helper.rb
 - lib/cocoapods-meitu-bin/helpers/spec_source_creator.rb
 - lib/cocoapods-meitu-bin/helpers/upload_helper.rb
+- lib/cocoapods-meitu-bin/helpers/worktree_identity.rb
 - lib/cocoapods-meitu-bin/native.rb
 - lib/cocoapods-meitu-bin/native/acknowledgements.rb
 - lib/cocoapods-meitu-bin/native/analyzer.rb