cweagans/composer-patches 是唯一稳定落地的补丁方案，但仅在 composer install/update 时触发，非实时生效；手动修改 vendor 必被覆盖，因 composer 严格按 composer.lock 解压原始包；插件必须安装在项目根 composer.json 中，配置需置于 extra.patches 下，路径相对根目录，补丁须为 lf 换行、无前缀的 git diff 格式。
cweagans/composer-patches 是唯一能在线上稳定落地的“热补丁”方案，但必须清楚：它不是实时生效，而是依赖 composer install 或 composer update 触发；所谓“秒级”只存在于本地调试阶段，线上生效必然伴随构建与部署周期。
为什么手动改 vendor 文件一定会失效
你改完 vendor/monolog/monolog/src/Logger.php 后跑通了，不代表它真能上线——composer install 会按 composer.lock 重新解压原始 zip 包，覆盖所有人工修改。这不是 bug，是 Composer 的确定性设计原则。
-
composer.lock记录的是包的哈希和压缩包 URL，不是你本地的代码状态 - CI 构建机没有你的编辑历史，
vendor/是空目录，从头解压 - Git 不该跟踪
vendor/，所以没人知道你改过哪三行
cweagans/composer-patches 必须装在项目根 composer.json 中
插件只读取项目根目录下的 composer.json 的 extra.patches 配置，子模块、私有 repo 或 require-dev 里写的配置全无效。
- 安装命令必须是：
composer require cweagans/composer-patches（不是--dev，除非你确定只在开发环境打补丁） - 如果已有
vendor/和composer.lock，先删掉再跑composer install，否则插件跳过已缓存包，不触发 patch - CI 脚本里不能加
--no-plugins，否则整个extra.patches配置被忽略
补丁文件格式和路径最容易出错的三个点
90% 的“补丁没应用”问题都卡在这三处，不是逻辑错，是格式或路径错。
- 补丁必须用
git diff在vendor/xxx/xxx目录下生成，开头要是diff --git a/src/Helper.php b/src/Helper.php，不能带vendor/前缀，也不能是 IDE 导出的带绝对路径 diff - 补丁路径写在
extra.patches里时，是相对项目根目录的，比如"patches/monolog-fix.patch"，不是"vendor/patches/..."或"./patches/..." - 文件换行符必须是 LF（Unix），Windows 的 CRLF 会导致
patch: unrecognized format，用dos2unix patches/*.patch可批量修复
补丁应用失败时怎么快速定位
别猜，直接看 composer install -v 输出里的三行关键日志：
- 有没有
Loading plugin cweagans\Composer\Patches\Plugin→ 没这行 = 插件根本没加载 - 有没有
Applying patches for monolog/monolog→ 没这行 = 配置位置错或包名不匹配（大小写敏感！） - 有没有
Reversed (or previously applied) patch detected!或Hunk #1 FAILED→ 补丁内容与当前包版本不兼容，得重生成
补丁不是一次写成就能永久有效，包版本一变，hunk offset 就可能偏移；上线前务必确认 composer.lock 里记录的补丁 SHA 和你本地一致，否则下次 composer update 就悄悄失效。
