Composer install 不会自动打补丁,必须安装 cweagans/composer-patches 插件并在 composer.json 的 extra.patches 中声明补丁,否则不触发;插件通过 composer require 安装后自动注册,补丁路径须匹配包结构,失败时需检查版本一致性、hunk 偏移及 Git 状态。
不会自动打补丁——它只还原依赖,不处理 patch。必须用
插件,且补丁声明必须写进
的
字段,否则根本不会触发。
怎么装
composer
-patches 插件
在项目根目录运行这条命令即可:
插件会自动注册,无需额外激活。安装后:
里会出现
条目,
也会记录插件版本。
注意:不要手动改
目录名或移动它——
依赖 vendor 下的原始包结构来定位文件,路径错位会导致 patch 应用失败,报
或
。
怎么在 composer.json 里写补丁配置
补丁必须放在
下,格式是:
关键点:
必须和
输出的包名完全一致(包括大小写、斜杠)
补丁路径支持相对路径(如
),也支持远程 URL(如
)
同一个包要打多个 patch,必须写成数组,顺序不能错:
—— 后一个 patch 依赖前一个已生效的代码状态
别把补丁写进
或
,那只会当普通包装,完全无效
补丁应用失败常见原因和应对
最常卡在
这类 hunk 偏移错误,本质是 patch 文件基于的源码版本和当前安装的包版本不匹配。
Composer 2.9.6
Composer 2.9.6 是 PHP 生态中高效、稳定的依赖管理工具。此版本在性能与兼容性上进一步优化,改进了依赖解析算法,提升大型项目中的安装与更新速度。它支持并行下载任务,显著减少等待时间,并增强了与私有仓库及镜像源的交互稳定性。同时修复了多项命令行交互与内存使用相关的缺陷,确保在复杂依赖关系下依然可靠运行。无论是新项目初始化还是现有系统维护,Composer 2.9.6 都能为开发者提供流畅、精准的依赖管理体验。
下载
先别急着重做 patch,试试这几个办法:
加
重新跑:
,看具体哪一行 offset 失败,快速定位改动点
在对应 patch 配置里加
键(值为布尔 true),让插件先反向打一次再正向打,有时能绕过 strict offset 检查
确认你锁的版本(
中
的 version)是否和 patch 生成时的 commit 一致;不一致就进
,用
重做 patch
补丁内容里如果出现
,而目标包没用 Git 管理(比如通过 zip 下载),
会直接失败——这时得确保 vendor 包是 Git 克隆下来的,或改用
兼容格式。
怎么验证补丁真生效了
别只信控制台输出的 “Applying patches”,得实锤:
进
,用
看有没有未提交修改(有说明 patch 已应用)
检查目标文件是否真被改了,比如打开
,搜 patch 里写的新增行
清掉 OPcache(
或重启 PHP-FPM),否则即使文件改了,PHP 还在跑旧字节码
框架缓存(如 Laravel 的
)也要清,避免补丁改的是配置逻辑但缓存没刷新
最容易被忽略的是:有些项目自己写了自定义
脚本,里面调用了
或类似逻辑,会覆盖或干扰
的行为——得检查
的
字段。
composer installcweagans/composer-patchescomposer.jsonextra.patchescomposer require cweagans/composer-patchescomposer.json"cweagans/composer-patches"composer.lockvendor/cweagans/composer-patchesfatal: not a git repositorycannot find file to patchextra.patches"extra": {
"patches": {
"monolog/monolog": {
"fix null coalesce in Logger::log": "patches/monolog-null-coalesce.patch"
}
}
}"monolog/monolog"composer showpatches/xxx.patchhttps://example.com/patch.diff"patches": ["desc1": "a.patch", "desc2": "b.patch"]requirerequire-deverror: patch failed: src/Logger.php:123--no-cache -vcomposer install --no-cache -v"revert": truecomposer.lockmonolog/monologvendor/monolog/monologgit diffdiff --git a/src/... b/src/...git applypatch -p1vendor/xxx/packagegit statusvendor/monolog/monolog/src/Logger.phpopcache_reset()php artisan config:clearpost-install-cmdgit applycweagans/composer-patchescomposer.jsonscripts