使用 composer-patches 打补丁分三步：安装插件、在 composer.json extra.patches 中声明补丁（支持远程 URL 或本地路径）、执行 composer install/update 触发应用；补丁不修改源码，仅下载后自动应用，适用于紧急修复，需及时跟进上游合并并移除。
直接用 composer-patches 为依赖包打补丁，核心就三步：安装插件、声明补丁、执行安装。它不修改源码仓库，而是下载后自动应用 patch 文件，适合紧急修复线上 bug 或等待上游合入前的临时方案。
安装 composer-patches 插件
项目根目录下运行：
-
composer require cweagans/composer-patches:^1.7（推荐 v1.7+，兼容 Composer 2.x） - 安装后 Composer 会自动启用插件，无需额外配置启用
在 composer.json 中声明补丁
在 extra 段落中添加 patches 配置，按目标包名组织：
"extra": {
"patches": {
"monolog/monolog": {
"Fix memory leak in StreamHandler": "https://github.com/Seldaek/monolog/pull/1234.patch",
"Avoid null dereference in JsonFormatter": "./patches/monolog-null-check.patch"
},
"laravel/framework": {
"Hotfix: session regeneration race condition": "./patches/laravel-session-race.patch"
}
}
}
- 补丁源支持远程 URL（GitHub PR 补丁链接、raw 文件）或本地相对路径（推荐放
patches/目录下） - 键名是补丁描述，不影响执行，但建议写清用途和影响范围
- 多个补丁按数组顺序依次应用，有冲突会报错并中断安装
触发补丁应用
补丁只在以下操作中生效：
-
composer install（首次安装依赖时） -
composer update vendor/package-name（更新特定包时） -
composer update（全量更新时，所有声明补丁都会重试应用）
注意：已安装的包不会自动重打补丁。如果想强制重应用，可先删 vendor/ 再 composer install，或加 --with-all-dependencies 确保依赖树完整重建。
验证与调试
补丁是否成功？看终端输出：
- 成功时会显示类似：
Applying patches for monolog/monolog→+ Fix memory leak... - 失败时明确提示文件路径、行号冲突，并终止安装
- 补丁内容需符合
git diff格式（含diff --git头和index行），用git apply --check xxx.patch可提前校验
补丁文件建议用 git diff 生成（从干净分支 checkout 后修改再 diff），避免手工编辑格式错误。
基本上就这些。补丁不是长期方案，记得同步跟进上游状态，及时移除补丁并升级到正式版本。
