composer install 不应用 patch 是因原生不支持，需安装 cweagans/composer-patches 插件并在 extra.patches 中正确配置路径与格式，否则补丁不会执行。
为什么 composer install 不应用 patch？
补丁没生效，大概率不是 patch 写错了，而是 Composer 默认根本不会处理 patch 文件。原生 Composer 不支持打补丁，必须借助第三方插件 —— 最常用的是 cweagans/composer-patches。它通过钩子在 post-install-cmd 和 post-update-cmd 阶段解压包后、自动应用 patch。
常见错误现象：composer install 成功但代码没变；patch 文件存在且路径正确，但 vendor/ 下对应文件内容未更新。
- 必须在
require-dev中显式安装插件：composer require --dev cweagans/composer-patches - 插件只在当前项目生效，不能靠全局安装
- 如果已运行过
composer install，需先删掉vendor/和composer.lock再重装，否则旧包缓存会跳过 patch 步骤
怎么在 composer.json 里写 patch 配置？
补丁配置必须放在根级 extra.patches 字段下，键是目标包名（格式为 vendor/name），值是 patch 描述数组。注意：不是所有包都支持任意路径 patch，必须确保 patch 是基于包发布时的源码结构生成的（即 git diff 时工作目录是该包的 vendor/vendor/name）。
示例：
"extra": {
"patches": {
"monolog/monolog": {
"Fix log level check": "patches/monolog-fix-level.patch"
},
"laravel/framework": [
{
"description": "Allow nullable middleware parameter",
"url": "https://github.com/laravel/framework/pull/45678.patch"
}
]
}
}
- 本地 patch 路径是相对于
composer.json的，不是相对于 vendor 或当前命令行路径 - 支持
url和path两种来源，但远程 URL 必须返回标准 unified diff（含diff --git头） - 同一个包可配多个 patch，用数组形式；单个 patch 可用对象（带 description）或纯字符串（仅 path）
- 若 patch 应用失败（比如 hunk offset 偏移过大），Composer 会报错并中断安装，不会静默忽略
composer-patches 的 patch 格式和常见失败原因
插件底层调用系统 patch 命令，因此必须符合 POSIX patch 格式。最常踩的坑是 patch 文件头不匹配：比如用 git diff 在项目根目录生成的 diff，会包含类似 a/src/Helper.php 和 b/src/Helper.php 的路径，但实际 vendor 包解压后没有 a/ b/ 前缀，导致找不到文件。
- 生成 patch 推荐用：
git diff --no-prefix origin/main src/Helper.php > patches/fix-helper.patch - 避免使用 IDE 自带的“复制差异”功能，它们常带额外空格或编码问题
- Windows 用户注意：patch 文件必须用 LF 换行，CRLF 会导致
malformed patch错误 - 如果 patch 修改了 vendor 包的
composer.json或自动加载映射，记得运行composer dump-autoload后续生效
如何调试 patch 是否真的被应用？
最直接的方式是加 -v 参数看详细日志：composer install -v。插件会在 “Applying patches…” 阶段逐条打印 patch 描述、路径和结果（OK 或 Failed）。
若仍不确定，可手动验证：
- 检查
vendor/vendor/name下目标文件是否已被修改 - 运行
composer show vendor/name查看安装版本，确认不是用了 dist 包（dist 包可能跳过 patch，建议设"preferred-install": "source"强制用 source） - 临时在
extra.patches里配一个明显错误的 patch（如错文件名），观察是否报错 —— 如果没报，说明配置根本没被读取，可能是字段位置写错（比如塞进了config而非extra）
真正容易被忽略的是：patch 生效依赖于包的安装方式（source vs dist）、Composer 版本（2.2+ 对 patch 兼容性更好）、以及插件自身是否被其他插件干扰（比如某些 lock 文件操作插件会提前终止流程）。别只盯着 patch 内容本身。
