composer install 默认不打补丁，需安装cweagans/composer-patches插件，并在composer.json的extra.patches中声明补丁路径或url，支持相对路径、远程url及多补丁顺序应用；补丁失败常见于版本不匹配导致hunk偏移错误，可尝试--no-cache -v调试、revert绕过或基于vendor重做patch；开发环境补丁可通过composer环境变量切换composer-dev.json实现；生效验证需检查git status、清理opcache及框架缓存，避免被自定义patch命令绕过。
composer install 时怎么应用指定 patch 文件
直接靠 composer install 不会自动打补丁——它只管下载包，不处理 patch。必须借助插件，最常用的是 cweagans/composer-patches。
先装插件：composer require cweagans/composer-patches。装完后，所有 patch 都得写进 composer.json 的 extra.patches 字段里，格式是："包名": ["描述", "patch 文件路径或 URL"]。
- patch 文件路径支持相对路径（如
patches/fix-null-coalesce.patch），也支持远程 URL（如https://example.com/fix-bug.patch） - 同一个包可以打多个 patch，按数组顺序依次应用；顺序错可能导致失败
- 如果 patch 是基于某个特定 commit 写的，而你锁的包版本不匹配那个 commit，
git apply很可能失败，报错类似error: patch failed
patch 文件内容不符合目标版本，怎么办
这是最常卡住的地方：patch 本身没问题，但目标包的源码结构变了，hunk 偏移错位，git apply 就会拒绝。
别急着重写 patch，先试两个低成本办法：
- 加
--no-cache和-v重新composer install，看具体哪一行 offset 失败，定位到改动点 - 在
extra.patches里给该 patch 加个revert键（值为true），让它反向打一次再正向打，有时能绕过 offset 检查 - 实在不行，用
git diff基于当前已安装的包版本重做 patch：进vendor/xxx/package，改完后git diff > ../patches/new.patch
如何让 patch 只在开发环境生效
有些 patch 是临时调试用的，上线不该带。Composer 本身没环境级 patch 开关，但可以靠 config.platform + 条件加载模拟。
更实际的做法是：把 patch 放进独立配置文件，用 COMPOSER 环境变量切换：
- 写两个
composer.json：主文件不含 patch，另存为composer-dev.json，里面加extra.patches - 开发时运行
COMPOSER=composer-dev.json composer install - CI 或部署脚本里确保用的是主
composer.json，自然跳过 patch
注意：cweagans/composer-patches 插件不会自动忽略 dev-only 的 patch，全靠你控制加载哪个 JSON。
patch 打成功了但代码没生效？检查这些地方
常见假象：命令没报错，composer install 显示 “Applying patches...”，但运行时 bug 还在。
- 确认 patch 是否真被应用：进
vendor/xxx/package，执行git status，看有没有未提交修改；或者git log -1 --oneline看最后一条是不是 “Apply patch xxx” - PHP opcode 缓存（OPcache）可能缓存了旧字节码，重启 PHP-FPM 或 CLI 进程，或临时关掉 OPcache 测试
- 如果 patch 修改的是类常量或静态属性，某些框架（如 Laravel）会在启动时预加载并缓存，需清
bootstrap/cache/*.php和storage/framework/cache - 别忽略
vendor/bin/patch—— 有些项目自定义了 patch 命令，优先走它，此时cweagans/composer-patches可能被绕过
patch 是临时手术刀，不是长期方案；能提 PR 到上游就别留在本地 JSON 里。
