composer install 不会自动打补丁，必须安装 cweagans/composer-patches 插件（Composer 2.2+ 用 ^2.0，旧版用 ^1.7），且 extra.patches 配置须置于项目根 composer.json 中、路径相对该文件、补丁为 LF 换行的无前缀 git diff，还需删除 vendor 和 composer.lock 后重装才能生效。
composer install 不会自动打补丁，必须装插件才生效
composer install 本身完全忽略 extra.patches 配置——它只解压包、写 autoload、生成 vendor/autoload.php，不调用任何 patch 工具。补丁逻辑由 cweagans/composer-patches 插件注入钩子实现，没装插件，extra.patches 就是纯 JSON 字符串，毫无作用。
必须显式运行：composer require --dev cweagans/composer-patches:^2.0（Composer 2.2+）
或composer require --dev cweagans/composer-patches:^1.7（Composer 1.x 或旧 CI 环境）
- 不能用
composer global require—— 全局安装对当前项目零影响 - 装完检查
composer.json的require-dev是否新增了该插件条目 - 如果之前已跑过
composer install，删掉vendor/和composer.lock再重来，否则缓存包跳过 patch 阶段
extra.patches 必须写在项目根 composer.json 里，路径要对
插件只读取项目根目录下的 composer.json，其他位置全无效：子模块的 composer.json、repositories 里定义的包、甚至 config.platform 都不会被扫描。
键名必须是标准包名格式，例如："laravel/framework" ✅"./vendor/laravel/framework" ❌"Laravel\Framework" ❌
- 值必须是对象或数组，不能是裸字符串嵌套在错误层级中
- 路径是相对于
composer.json文件的，不是 shell 当前路径，也不是vendor/目录 —— 推荐统一放patches/子目录下 - 路径含空格、中文或特殊字符（如
my fix.patch）会导致 JSON 解析失败，插件静默跳过该条目
补丁文件内容必须是 LF 换行 + 无前缀的 git diff
插件底层调用系统 patch 或 git apply，所以补丁格式必须严格：
- 换行符必须是 Unix 风格（LF），Windows 的 CRLF 会导致应用崩溃；可用
file patches/*.patch确认 - diff 头必须匹配 vendor 解压后的实际路径，例如：
diff --git a/src/Helper.php b/src/Helper.php✅diff --git a/vendor/laravel/framework/src/Helper.php b/vendor/laravel/framework/src/Helper.php❌ - 生成方式推荐：
cd vendor/laravel/frameworkgit diff --no-prefix HEAD src/Helper.php > ../../patches/laravel-helper-fix.patch - GitHub PR 的
.patch链接通常可用，但需确保返回的是标准 unified diff（含diff --git和index行）
验证是否真正生效，别只看 install 成功
composer install 返回 “success” 完全不代表补丁进了 vendor/。关键看三件事：
- 加
-v参数重跑：composer install -v | grep "Applying patch"—— 没这行输出，说明配置没加载或插件失效 - 进
vendor/xxx/package目录，手动git status看文件是否真被修改；别信 IDE 缓存或文件浏览器刷新 - 清理 OPcache 和框架缓存（如 Laravel 的
php artisan config:clear），否则代码改了也看不到效果 - 某些自定义脚本或 CI 流程里写了
composer install --no-scripts，会禁用插件钩子，得去掉这个 flag
最常被忽略的一点：补丁只在 install 或 update 时触发，改完 composer.json 后不重装，就等于什么都没做。
