别再直接改 vendor 了！教你优雅地给 Composer 包打补丁

在 PHP 开发中，我们可能会遇到需要修改第三方 Composer 包的情况。直接修改 vendor 目录下的文件虽然简单，但会导致后续 composer update 时覆盖修改。本文分享一种优雅的解决方案——为 Composer 包制作补丁，让你的修改持久有效，同时保持项目可维护性。

为什么需要打补丁？

当第三方库存在 bug 或缺少功能，但作者尚未修复时，直接修改 vendor 目录会带来以下问题：

• 无法使用 composer update 更新包
• 代码版本难以追踪
• 团队协作时容易冲突

通过制作补丁，你可以：

✅ 保留修改不被覆盖
✅ 与团队共享修改
✅ 保持项目结构清晰

详细操作步骤

1. 复制需要修改的包

cp -rf vendor/hyperf/watcher watcher

这将把 vendor/hyperf/watcher 目录备份到项目根目录的 watcher 文件夹中，以便对比制作补丁文件。

2. 修改包文件内容

使用你喜爱的编辑器（VS Code、PHPStorm 等）打开 vendor/hyperf/watcher 目录，进行所需的修改。

3. 生成补丁文件

git diff --no-index --no-prefix watcher vendor/hyperf/watcher > patches/hyperf.watcher.patch

这会将原始的 watcher 与 vendor/hyperf/watcher 的差异保存为
patches/hyperf.watcher.patch 文件。

4. 修正补丁文件路径

打开
patches/hyperf.watcher.patch，确保所有文件路径都包含 vendor/ 前缀。例如：

- diff --git watcher/src/watcher.php vendor/hyperf/watcher/src/watcher.php
+ diff --git vendor/hyperf/watcher/src/watcher.php vendor/hyperf/watcher/src/watcher.php
index 01587b6..dc05ae3 100644
- --- watcher/src/watcher.php
+ --- vendor/hyperf/watcher/src/watcher.php

⚠️ 重大：如果没有这一步，应用补丁时会失败

5. 应用补丁

patch -p0 -N < patches/dev/*.patch
find vendor/ -name '*.rej' | xargs rm -f

• -p0 表明不移除路径前缀
• -N 避免重复应用一样补丁
• *.rej 是重复应用补丁产生的冲突文件，清理掉

6. 自动化应用补丁

将补丁应用命令保存到 patches/patch.sh：

#!/bin/bash
patch -p0 -N < patches/dev/*.patch
find vendor/ -name '*.rej' | xargs rm -f

在 composer.json 中添加：

{
    "scripts": {
        "post-autoload-dump": ["bash patches/patch.sh"]
    }
}

这样每次运行 composer install 或 composer update 后，补丁会自动应用。

实际应用示例

我们需要修复 hyperf/watcher 包在 WSL docker 环境中无法监听文件变化的 bug：

• 复制包：cp -rf vendor/hyperf/watcher watcher
• 修改 vendor/hyperf/watcher/src/Driver/FindNewerDriver.php 中的 76 行，将 ‘&’ 改为 ‘&&’
• 生成补丁：git diff … > patches/hyperf.watcher.patch
• 修正路径后应用补丁
• 将补丁文件提交到项目 Git 仓库

目前，团队成员运行 composer update，都会无感使用你修改后的补丁包。

最佳实践

• 补丁命名规范：patches/package.name.patch（如 patches/hyperf.watcher.patch）
• 版本控制：将补丁文件提交到 Git 仓库
• 补丁分类：按功能或问题类型组织补丁（patches/fix/、patches/features/）
• 定期检查：当上游包更新后，检查补丁是否仍适用

结语

通过给 Composer 包打补丁这种方法，你既能快速解决问题，又不会破坏项目的可维护性。避免了直接修改 vendor 目录的陷阱，让团队协作更顺畅。

下次当你需要修改第三方包时，不妨试试这个方法，让开发流程更高效、更专业！

本文代码已通过实际项目验证，适用于 Laravel、Hyperf 等主流 PHP 框架。