Composer删除项目依赖后如何清理残留引用

Composer删除项目依赖后如何清理残留引用

composer remove 执行后 vendor 目录仍有文件？

这事儿其实挺常见的，尤其是如果你还在用 Composer 2.1 或更早的版本。很多人会纳闷：明明执行了删除命令，怎么 vendor/ 文件夹里那些文件还在？

原因很简单：composer remove 这个命令，默认只干两件事——更新 composer.json 里的依赖声明，以及同步修改 composer.lock 文件。至于 vendor/ 目录下的物理文件，它默认是不碰的。真正的清理工作，要等到你后续执行 composer install 或 composer update 时才会触发。

当然，从 Composer 2.2 版本开始，行为有所改变，默认会同步删除对应的目录。但这里有两个常见的“坑”：一是如果你用了 --no-update 参数跳过了更新步骤，二是命令执行过程中因为网络或权限问题中途失败了。这两种情况，残留文件几乎是必然的。

那怎么解决呢？可以按这个顺序来：

• 首先，去 composer.json 文件里确认一下，看看 require 或 require-dev 部分里，那个包的名字是不是真的彻底消失了。这里要特别注意大小写和供应商名称的拼写。
• 然后，运行 composer install。这是最稳妥、最标准的同步操作。composer update 虽然也能触发清理，但它会尝试升级所有其他包，如果你只是想单纯清理，用 install 更合适。
• 如果还不行，或者你怀疑锁文件本身已经被污染了，可以尝试更彻底的方法：直接删除 composer.lock 文件，再运行 composer install。不过要记住，这相当于重建整个依赖树，只建议在开发环境操作。

autoload 文件里还留着已删包的命名空间？

这个问题更隐蔽，也更容易在后期引发诡异的错误。你以为包删干净了，但 Composer 的自动加载映射文件可能还记着它。

像 vendor/composer/autoload_psr4.php 或 autoload_classmap.php 这类文件，里面保存着类名和文件路径的映射关系。如果它们没有更新，你的代码可能还能通过 use 语句“引用”到那个已经被删除的包里的类，但实际上引用的是一堆已经不存在的代码，运行时崩溃是迟早的事。

所以，composer dump-autoload -o

具体可以这么做：

• 立即运行 composer dump-autoload -o。特别是如果你在用 Lara vel 9 或更高版本，它默认启用了 classmap-authoritative 模式，不执行这一步几乎肯定会出问题。
• 命令执行后，可以手动打开 vendor/composer/ 目录下的那几个 autoload_*.php 文件，用搜索功能找找目标包名，确认相关的条目已经消失了。
• 还有一个高级“坑”：如果你服务器上启用了 OPcache 或 APCu 这类字节码缓存，光更新文件还不够，PHP 可能还会从缓存里读取旧的加载规则。所以记得同时清理一下缓存：调用 opcache_reset() 函数或者执行 apcu_clear_cache()。

代码里还有 use、new、配置注册等残留？

这才是最需要警惕的地方。composer remove 命令的职责范围非常明确：它只管依赖声明和自动加载。你的源代码、配置文件、注册的服务，它一概不动。

所以，经常会出现这种情况：依赖包从 vendor/ 里清走了，自动加载也更新了，但项目一运行，还是抛出 Class not found 或者 Driver not supported 这样的错误。根源就是代码里还有对已删除包的调用。

怎么彻底清查呢？

• 最直接的方法，就是在你的项目源码目录里全局搜索那个包的关键词。比如在 Linux 或 macOS 终端里，可以这样：grep -r “monolog” app/ src/ config/ --include=“*.php”。注意，如果包名里有反斜杠（命名空间分隔符），搜索时需要转义，比如搜索 “use Monolog\”。
• 有几个地方是重灾区，需要重点检查：
  • config/app.php 这样的框架配置文件中，providers（服务提供者）和 aliases（门面别名）数组。
  • 自定义的服务提供者文件。
  • 事件监听器、队列任务等注册类名的地方。
  • 代码中的注解，比如 Doctrine 的实体注解、PHPStan 的规则注解。
  • 甚至数据库迁移文件里，有时也会用字符串形式硬编码类名。
• 另外，别指望包自己会帮你清理。虽然 Composer 支持 post-remove 脚本，但几乎没有包作者会去实现它。所以，清除缓存、删除配置文件、卸载中间件这些“善后”工作，都得你自己来。

怎么确认某个包真没被任何依赖间接引用？

依赖关系就像一张网，不能只看表面。一个包，即使没直接出现在你的 composer.json 里，也可能被另一个你正在使用的包所依赖（即传递性依赖）。如果你贸然把它从 vendor/ 里删了，而它的“父依赖”还在，运行时就会因为找不到类而崩溃。

所以，别靠猜，用工具来验证：

• 使用 composer depends vendor/package-name 命令。这个命令会告诉你，当前项目里还有哪些已安装的包依赖着它。如果返回结果是空的，那说明这个包现在是“孤岛”，可以安全移除。
• 想看得更全面，可以查看完整的依赖树：composer show --tree | grep -A5 -B5 vendor/package-name。这样你能确认它是不是某个依赖链末端的“叶子节点”。
• 还有一个更彻底的“临时验证法”：先把整个 vendor/ 目录和 composer.lock 文件删除，然后运行 composer install --dry-run（--dry-run 参数表示模拟运行，不实际安装）。仔细观察命令输出的 “Installing” 列表。如果目标包没有出现在这个列表里，那才能百分之百确定，项目当前的依赖状态确实不再需要它了。

最后，分享一个特别容易踩的坑：那些仅用于开发环境的包（比如 phpunit/phpunit）。在生产环境用 composer install --no-dev 安装时，它们确实不会被装上。但是，如果你的 composer.lock 文件是在本地开发环境（带着 dev 依赖）生成的，然后提交到了线上，那么这些 dev 包的目录就可能残留在 vendor/ 里，并且 composer show 命令依然会列出它们。这时候，首先要确保你的 composer.lock 文件本身是在正确的环境（生产环境）下生成的，或者已经清理干净了。