Composer本身不处理补丁，需依赖cweagans/composer-patches插件；未生效主因是插件未安装、配置位置错误、加了--no-plugins参数或补丁格式不规范。
Composer 本身完全不处理补丁——composer install 或 composer update 默认只会下载和解压包，不会读取、解析或应用任何 .patch 文件。所有“打补丁”行为都依赖第三方插件，目前最稳定、主流且兼容 Composer 2.x 的方案是 cweagans/composer-patches。
为什么 composer install 后代码没变？
这不是 patch 写错了，而是插件根本没装，或者装了但没触发。常见情况包括：
-
cweagans/composer-patches没在require-dev中显式安装：必须运行composer require --dev cweagans/composer-patches - 已存在
vendor/和composer.lock：插件只在包解压后执行 patch，缓存包会跳过这步；必须删掉vendor/和composer.lock，再跑composer install - 配置写在了错误的
composer.json里：比如子模块或私有 repo 的配置文件中，而实际项目根目录的composer.json里没有extra.patches - 命令加了
--no-plugins：CI 脚本或本地调试时误加，直接禁用所有插件
extra.patches 配置怎么写才有效？
必须放在项目根目录 composer.json 的顶层 extra 字段下，键名是目标包的完整 vendor/name（如 laravel/framework），值是一个对象，每个 key 是描述，value 是补丁路径（相对于 composer.json）：
"extra": {
"patches": {
"monolog/monolog": {
"Fix handler stack overflow": "patches/monolog-stack-fix.patch"
},
"symfony/http-foundation": [
{
"description": "Allow empty Content-Type",
"path": "patches/symfony-content-type.patch"
}
]
}
}
注意：
- 路径不能含空格或中文；推荐全小写 + 短横线，如
patches/laravel-middleware-null.patch - 同一个包多个 patch 要用数组格式，顺序重要：后一个 patch 基于前一个已应用的结果
- 远程 URL 补丁也支持，但需确保可访问且返回标准 unified diff（
diff -u格式）
补丁文件生成和格式踩坑点
补丁不是随便改完保存就行，它得能被系统 patch 命令或 git apply 正确识别：
- 必须用
git diff --no-prefix生成，例如：git diff --no-prefix origin/main src/Helper.php > patches/fix-helper.patch；带a/src/b/src/前缀的原始 diff 很可能失败 - 换行符必须是 LF（Unix），Windows 的 CRLF 会导致
patch: unrecognized format；可用file patches/*.patch检查 - 补丁内容路径要相对于包根目录，不是项目根目录：比如改的是
src/Helper.php，补丁里就该是diff --git a/src/Helper.php b/src/Helper.php，不是vendor/monolog/monolog/src/Helper.php - 如果目标包版本和补丁生成时的版本不一致，hunk 偏移错位会导致
patch failed；优先用当前vendor/下的包重新生成补丁
怎么确认补丁真的生效了？
别只看命令是否成功退出，得验证结果：
- 加
-v参数运行：composer install -v，搜索输出里的Applying patch行；没这句说明配置没加载或插件没启用 - 直接检查
vendor/下对应文件内容是否变更，比对补丁中的 hunk 是否已写入 - 补丁失败时 Composer 会中止并报错，错误信息通常包含具体哪一行 offset 不匹配，据此定位是补丁过期还是路径不对
- CI 或部署环境容易忽略开发时的补丁配置：确保
COMPOSER环境变量没指向其他composer.json，且没全局禁用插件
最麻烦的从来不是写补丁，而是补丁生效后没人记得它还挂着——尤其当上游已修复、版本升级后 patch 冲突或静默失效。定期 grep extra.patches 并核对对应包的最新 release note，才是长期可控的关键。
