Composer 安装带补丁包需借助 composer-patches 插件，在 extra.patches 中定义 Unix 换行、路径匹配的补丁文件，配合 dump-autoload 清缓存并验证 vendor 文件修改，避免因版本不兼容、路径错误或补丁被覆盖导致失效。
Composer 安装带补丁的包，本质是打补丁，不是改包源
直接用 composer require 装不了「已打补丁」的包——Composer 本身不支持在安装时自动应用补丁。真正可行的路径是：先装原包，再用插件在本地打补丁。关键不在「怎么装」，而在「谁来打、何时打、补丁放哪、怎么验证」。
必须用 composer-patches 插件，且版本要对得上 Composer
composer-patches 是事实标准，但它的兼容性很敏感：
- Composer 2.x 用户必须用
v1.7.2+（推荐^1.7），旧版如v1.6在 Composer 2 下会静默跳过补丁 - 补丁定义必须写在
extra.patches下，不是scripts或自定义配置项 - 插件启用后，
composer install和composer update都会触发补丁应用（除非加--no-plugins）
补丁文件位置和格式稍有偏差就失败
常见报错如 Patch could not be applied 或 Cannot apply patch，90% 出在路径或格式上：
- 补丁必须是 Unix 换行符（
\n），Windows 的\r\n会导致解析失败 -
diff头部路径要匹配 vendor 目录结构，比如补丁里写--- a/src/Helper.php，实际文件必须在vendor/vendorname/packagename/src/Helper.php - 推荐用
git diff --no-index或从 Git commit 生成补丁（git format-patch -1 <commit></commit>），避免手工编辑出错 - 补丁文件建议放在项目根目录下
patches/子目录，路径写相对路径即可，例如："patches/my-fix.patch": "vendorname/packagename"
打补丁后代码没生效？检查是否被缓存或覆盖
补丁看似成功，但运行时无效，通常因为：
- Composer 的 autoloader 缓存未刷新：执行
composer dump-autoload，别只信install自动触发 - 补丁被后续
composer update冲掉：如果包升级到新版本，而补丁没适配新代码结构，插件会跳过并报 warning（默认不中断），需手动检查日志输出 - 多个补丁冲突：同一文件被打多次，
composer-patches按字典序加载，顺序不可控，建议合并为单个补丁文件 - 补丁目标文件被其他插件（如
hirak/prestissimo）或 CI 环境清理掉：确认vendor/下对应文件确实被修改过（用git status vendor/vendorname/packagename查）
补丁不是黑魔法，它把修改硬塞进 vendor 目录；一旦你忘了它存在，或者换了环境没同步补丁文件，问题就会突然冒出来。最麻烦的从来不是打不上，而是「以为打上了，其实没打」。
