遇到“Your local changes would be overwritten by merge”错误时，是因Git检测到vendor中通过Git安装的包存在未提交的本地修改。Composer更新时会拉取远程代码，而Git拒绝覆盖这些变更。若修改不重要，可进入对应包目录执行git reset --hard HEAD和git clean -fd清除更改后重新运行composer update；若需保留修改，应将其提交到自定义分支（如patch-fix），并在composer.json中将该包版本指向dev-patch-fix。最佳实践是避免直接修改vendor代码，推荐fork原仓库并在自己的分支中维护定制功能，或使用cweagans/composer-patches等工具管理补丁。为预防问题，应规范开发流程，禁止提交vendor至版本控制，并借助CI、PHPStan等工具提升代码质量，建立可持续的依赖管理模式。
当你在使用 Composer 更新依赖时遇到 "Your local changes would be overwritten by merge" 这类提示，其实问题并不在 Composer 本身，而是 Git 检测到你对某个通过 Git 安装的包（通常是通过 repositories 配置引入的私有或 fork 的包）做了本地修改。Composer 在更新时会调用 Git 拉取最新代码，而 Git 拒绝覆盖你的未提交更改。
问题原因
你可能手动修改了 vendor/ 目录下某个通过 Git 加载的第三方库的代码。虽然这种做法常见于临时调试，但 Git 会把这些改动视为“未提交的本地变更”。当 Composer 尝试更新这个包时，Git 无法干净地合并远程更新，于是报错阻止操作。
解决方案
根据你的实际需求选择以下方式之一：
-
放弃本地修改，强制更新
如果你的修改不重要，可以直接丢弃：
cd vendor/your-vendor/your-package git reset --hard HEAD git clean -fd
然后回到项目根目录重新运行：
composer update
-
保留修改：提交到自己的分支
如果你确实需要保留修改，应将这些改动提交到你自己的 Git 分支中。例如：
cd vendor/your-vendor/your-package git checkout -b patch-fix git add . git commit -m "Fix something"
然后在 composer.json 中指定使用该分支：
"require": {
"your-vendor/your-package": "dev-patch-fix"
}
-
避免直接修改 vendor
最佳实践是不要手动改 vendor 里的代码。如果需要定制功能，建议：
- fork 原始仓库，在自己的版本中修改并维护
- 通过 Composer 使用你的 fork：
"repositories": [
{
"type": "git",
"url": "https://github.com/your-username/your-package"
}
]
- 或者考虑用 patch 工具（如 cweagans/composer-patches）自动打补丁
预防措施
为了减少这类问题：
- 把 vendor 目录设为只读（开发团队统一规范）
- 使用 CI 检查 vendor 是否被提交（不应该提交 vendor 到 Git）
- 用 PHPStan、Rector 等工具替代手动修改第三方代码
基本上就这些。关键是理解 Composer + Git 在处理可写源码包时的行为逻辑。你不该长期停留在“强行覆盖”的操作上，而是建立可持续维护的依赖管理方式。
