Magento 2 项目在 composer install 或升级时突然提示 patch cannot be applied，不能直接把补丁配置删掉继续部署。补丁可能仍在修复业务 Bug 或安全问题；也可能上游新版本已经包含同等修复。先确定补丁针对哪个包、哪一版源码，以及失败发生在哪一个文件块。

锁定实际安装版本与补丁目标

composer show vendor/package
composer why vendor/package
composer validate
composer install -vvv

composer.lock 决定 install 的准确版本。开发环境能应用、生产失败时，比较 lock 文件、Composer 版本、patch plugin 版本和 PHP 平台配置，不要只比较 composer.json。

补丁标题和文件名不是可靠依据。打开 patch header，确认路径指向目标包中的真实文件，并检查源码上下文是否仍存在。上游只改了几行空格、命名空间或方法签名，就可能让 hunk 无法匹配。

区分已经合入与发生冲突

搜索补丁新增的关键代码。如果新版本已经包含同样逻辑，重复应用会失败，此时可以在确认发布说明和实际源码后移除补丁；如果上游实现不同，必须重新评估旧补丁是否仍适用，不能机械刷新行号。

对安全补丁，要核对 Adobe 对当前 Magento 版本的适用范围和替代版本。不要因为构建失败就悄悄跳过，也不要把一个为旧版本生成的补丁强行应用到新版本。

patch level 和工作目录会改变路径

补丁里的 a/、b/、包根目录和 Composer 插件的 depth/level 配置必须匹配。可以在目标包副本中使用 dry run 观察：

patch --dry-run -p1 < fix.patch
patch --dry-run -p0 < fix.patch

只在隔离的构建目录执行，不要直接修改生产 vendor。dry run 能说明路径层级和具体失败 hunk，但最终仍应让 Composer 构建流程自动、可重复地应用。

注意同一文件上的补丁顺序

多个补丁按顺序修改同一区域，前一个成功后会改变后一个的上下文。列出实际应用顺序，检查不同模块是否携带重复补丁。升级 patch plugin 后顺序规则变化，也可能导致过去能构建的项目失败。

不要把修改后的 vendor 提交成解决方案

手工修改 vendor 能让当前服务器运行，却无法在下一次 install、扩容节点或 CI 构建中复现。正确做法是更新补丁、升级目标包、改为自有模块扩展，或在确认上游已修复后移除补丁，并让干净环境重新安装。

完成处理后删除构建产物，在全新目录使用同一 lock 文件执行 install、编译和自动测试。特别验证补丁原本修复的场景，而不是只以“Composer 没报错”作为成功标准。