cweagans/composer-patches 插件必须以 --dev 方式安装到项目中，配置需置于 composer.json 的 extra.patches 下，路径相对于该文件，补丁须为 LF 换行、无前缀的 unified diff，且需重装 vendor 和 lock 文件才能生效。
必须装插件，且补丁只在 composer install 或 composer update 时触发——不是“装完就生效”，也不是“改完 composer.json 就自动重打”。
怎么装 cweagans/composer-patches 插件才真正起作用
插件必须作为开发依赖显式安装到当前项目，全局安装无效：
-
composer require --dev cweagans/composer-patches:^1.7（推荐^1.7，兼容 Composer 1.x 和 2.x） - 如果项目锁死在 Composer 1.x（如旧 CI），别硬升插件到 v2.x，降级到
^1.7更稳 - 装完后不用手动启用，它会自动注册钩子，但仅对当前项目的
composer install/composer update生效 - 已运行过
composer install的项目，得先删掉vendor/和composer.lock再重装，否则缓存包跳过 patch 步骤
extra.patches 配置写在哪、怎么写才被识别
补丁配置必须放在项目根目录 composer.json 的顶层 extra.patches 字段里，不是 config、不是 scripts、也不能嵌套在子模块的 composer.json 中：
- 键是目标包名，格式严格为
vendor/name（如laravel/framework，不能写成laravel或framework） - 值可以是对象（带描述）或字符串（仅路径），例如：
"laravel/framework": { "Fix null middleware param": "patches/laravel-middleware-null.patch" } - 同一个包多个补丁，必须用数组：
"monolog/monolog": [ { "description": "Fix memory leak", "url": "https://...patch" }, { "description": "Avoid null deref", "path": "patches/monolog-null-check.patch" } ] - 路径是相对于
composer.json的位置，不是相对于命令行当前路径，也不是 vendor 目录 —— 推荐统一放patches/子目录下
补丁文件路径和内容为什么总不生效
90% 的失败源于路径错位或 patch 格式不兼容：
- 补丁文件路径含空格或中文？直接解析失败，用短横线命名最安全（如
fix-validation-null.patch） - 补丁必须是 Unix 换行符（LF），Windows 的 CRLF 会导致
git apply崩溃；用file patches/*.patch确认 - 补丁头必须匹配包解压后的实际路径：用
git diff --no-prefix origin/main src/Helper.php > patches/fix-helper.patch生成，别用带a/src/b/src/前缀的原始 diff - 远程 URL 补丁必须返回标准 unified diff（含
diff --git行和index行），GitHub PR 的.patch链接通常可用 - 补丁应用失败时 Composer 会中止并报错，不会静默忽略；加
-v参数看输出里有没有Applying patch这行
补丁没进 vendor 怎么快速验证和排查
别猜，用这三步定位根本原因：
- 运行
composer install -v，搜索输出中的Applying patches for或Applying patch—— 没这句说明配置根本没加载，检查composer.json是否在正确位置、字段名是否拼错 - 确认补丁目标包版本是否匹配：如果 patch 是基于
v10.12.3生成的，而composer.lock锁的是v10.11.0，hunk offset 很可能偏移失效 - 临时禁用所有干扰项：
composer install --no-plugins --no-scripts -v，排除其他插件影响；再试composer install -v - 终极干净验证：删掉
vendor/和composer.lock，再跑composer install -v—— 这是最接近 CI 环境的测试方式
补丁机制本身简单，但路径相对性、换行符、diff 前缀、缓存干扰这四点最容易被忽略。每次改完补丁或升级包版本，都建议重新跑一遍 composer install -v 看日志，而不是只检查 vendor 文件是否“看起来变了”。
