PHP Composer更新依赖时如何避免丢失对已安装包的自定义修改

直接修改vendor/目录下的第三方源码本身就不符合Composer的设计逻辑：vendor是Composer自动生成的依赖存放区，本身不纳入项目版本控制，执行composer update的时候，Composer会按照官方源的文件全量重建对应目录内容，未留存的本地修改被覆盖是必然结果。
下面是能完整保留自定义改动、正常执行版本更新的可落地方案：

方案1：使用补丁机制留存所有自定义改动（最推荐） #

这是对原有依赖流程侵入性最低的常规方案

• 先把所有针对第三方包的代码改动整理成标准diff格式的补丁文件，统一存放在项目根目录的patches/文件夹，这个文件夹要加入项目git版本控制
• 安装Composer专用的补丁管理插件，执行composer require cweagans/composer-patches
• 在composer.json的extra配置段，逐条登记每个补丁的对应信息：包括补丁指向的目标第三方包名称、补丁文件路径、补丁的用途说明
• 后续正常执行composer update即可：每次Composer拉取完官方最新的依赖包，都会自动按配置依次应用你留存的所有补丁。如果新版本的官方代码和你的补丁存在逻辑冲突，Composer会直接抛出明确的报错提示，你可以针对性调整补丁内容，不会出现自定义改动被悄无声息覆盖的问题。

方案2：自定义改动量较大时，使用本地仓库关联依赖 #

如果针对某个包的修改范围很广、改动行数很多，仅靠补丁维护的成本会比较高，这时候可以改用本地自定义包的方式

• 把需要修改的第三方包完整复制一份，存放在项目根目录下的packages/文件夹（纳入git版本控制），在这个独立的副本里完成所有自定义代码修改
• 在composer.json的repositories配置段，声明这个本地路径类型的自定义仓库，指定存放自定义包的目录路径
• 把原本对该官方包的版本依赖约束，调整为指向你本地自定义包的版本标识，比如将原本的"vendor/package": "^2.0"改为"vendor/package": "dev-custom"
• 后续跟进官方包版本更新时，只需要把官方最新版本的代码合并到你本地的自定义包副本中即可，不会出现原有改动被全量覆盖的问题。

方案3：临时应急的简易处理（不推荐长期使用） #

如果短期没有版本更新需求，可以直接锁定对应依赖的版本，避免执行更新时覆盖本地修改

• 在composer.json中把需要修改的包的版本约束，从范围匹配（比如^1.2、~1.2）修改为精确的固定版本号（比如1.2.3）
• 这种方式下，执行composer update时Composer不会主动拉取该包的更高版本，你直接修改vendor目录下的文件也不会被覆盖
• 缺点：会彻底失去该包的后续安全更新、功能迭代内容，且每次部署新环境时都需要手动重新同步修改过的文件，长期维护成本极高，仅适合临时应急使用。

通用避坑提醒 #

• 绝对不要把vendor目录纳入项目的git版本控制，这会打乱Composer的依赖校验、更新流程，引发大量难以排查的问题
• 所有自定义改动必须存储在项目本身的版本控制目录下（如补丁目录、本地自定义包目录），不能仅存放在随时会被重建的vendor目录中

内容的提问来源于stack exchange，提问作者Iskren