如果你维护过任何一个用 PHP 写的 Web 项目大概率对这段输出不陌生在终端敲下composer update光标停在Loading composer repositories with package information这一行久久不动接着慢慢吐出Updating dependencies然后屏幕底部冒出一句 “Your requirements could not be resolved to an installable set of packages.”后面还挂着 Problem 1、Problem 2 一长串。第一次碰到时我整个人是懵的以为项目代码写错了什么后来才发现这一整段输出其实每一步都有明确的含义理解了它你就读懂了 Composer 这套依赖管理工具的核心逻辑。这篇文章就围绕这个场景展开把 Composer 依赖解析流程、报错排查链路、平台兼容检查、镜像与缓存加速、composer.lock 的工程实践一次讲透。适合刚把 PHP 项目跑起来的入门者也适合被线上composer install卡到怀疑人生的老手。1. 那两行卡顿输出背后Composer 依赖解析的完整流程很多人把 Composer 当成PHP 的 npm / pip装上就能用但一遇到输出卡住或报错就抓瞎因为没有建立它到底在做什么的心智模型。我们先从最基础的执行流程说起。1.1 从 composer.json 到 Loading composer repositories第一行输出做了什么严格来说Loading composer repositories with package information不是一行独立的代码输出而是 Composer 的 Installer 在初始化阶段打印的阶段提示。翻译过来是正在从所有配置的软件仓库加载包信息这个动作发生在连接仓库、拉取元数据时。Composer 的仓库repositories概念很容易和 Git 仓库混为一谈。这里的 repo 指的是存放包信息的地方它有两层来源默认的 Packagistrepo.packagist.org和你在 composer.json 里通过repositories字段额外声明的 VCS 仓库、路径仓库或 artifact 仓库。Composer 会把所有这些源合并成一份可用的包列表再去做版本求解。这里有个关键历史差异。Composer 1 时代Packagist 对外提供的是 provider-includes 元数据每次运行都要把一大批 JSON 文件拉下来才能知道某个包有哪些版本慢得离谱。Composer 2 改为 metadata-url 按需请求机制只有当你真的需要某个包的信息时它才去请求对应的元数据片段。这也是为什么同样一个项目从 Composer 1 升到 2 之后Loading composer repositories这行几乎一闪而过。如果你在这行卡了很久大概率是网络层面的问题默认源在国外或者公司内网访问外网受限。后面第四章我会详细说镜像配置。1.2 Updating dependencies 是在解一道 SAT 题Updating dependencies是 Composer 开始真正干活的标记。这个阶段它会拿到第一步收集到的所有包的版本信息再结合根项目 composer.json 的require和require-dev交给内部的 Solver 去计算一套最合适的版本组合。Composer 用的求解器本质上是 SAT布尔可满足性算法每个包的不同版本相当于一个变量包的依赖关系和版本约束相当于一组子句求解器要找出一组赋值让所有子句都为真。听起来很深实际行为你可以理解成拼图——A 说我需要 1.0 的 BB 说我需要 ext-json 且不接受 C 2.0C 说我只能在 PHP 8 以上跑求解器必须找到一块恰好同时满足这些条件的拼图。这个阶段卡住一般有两个原因。一是约束写得过宽候选版本数量爆炸二是某个包的元数据包含了大量 dev 分支版本导致求解空间膨胀。多数情况下不是死循环而是在进行大量尝试。你可以在命令里加--profile看耗时分布也可以用-vvv看到详细的求解信息——虽然那个输出量对普通人来说基本是乱码但至少能确认它没死。1.3 从 Resolving 到 Installing你看到的每个阶段分别代表什么正常执行composer update你会连续看到几行阶段提示Loading composer repositories with package information收集元数据。Updating dependencies运行求解器确定要安装的确切版本。Lock file operations/Installs: xxx packages展示本次更新涉及的包数量。Package operations下的Installing / Updating / Removing实际下载并安装或删除包。Generating autoload files根据最终的包列表重新生成 PHP 自动加载文件。如果你只是在跑composer install且 composer.lock 存在且有效阶段会更简单直接进入Installing dependencies from lock file不再做Updating dependencies。这个行为的差异是理解 Composer 安装锁定的基石我会在第五章展开。2. Your requirements could not be resolved依赖冲突的完整排查链路这一行可以说是我见过最多的 Composer 报错。它后面的完整句是Your requirements could not be resolved to an installable set of packages.翻译过来是你的依赖要求无法被解析成一个可安装的包组合。很多人一看到这个就急着去改 composer.json或者把镜像切来切去其实关键在于读懂它下面那一串 Problem。2.1 先把一段典型报错逐行读明白假设你执行composer update得到类似这样的输出Loading composer repositories with package information Updating dependencies Your requirements could not be resolved to an installable set of packages. Problem 1 - Root composer.json requires phpunit/phpunit ^9.0 - satisfiable by [phpunit/phpunit[9.0.0, ..., 9.6.10]]. - phpunit/phpunit 9.6.10 requires php 7.3 - your php version (7.2.34) does not satisfy that requirement.第一行说的是根项目 composer.json 里要求 phpunit/phpunit ^9.0而现有仓库里满足这个约束的版本有 9.0.0 到 9.6.10 这一堆。第二行说的是其中一个版本 9.6.10 要求 PHP 版本 7.3但当前环境是 PHP 7.2.34不满足。于是求解器无论选哪个 9.x 版本都无法消除这个冲突只能报错。注意报错里的版本列表通常会省略中间版本号写成[phpunit/phpunit[9.0.0, ..., 9.6.10]]这是 Composer 在压缩展示不代表只有这两个版本可用。很多人看不懂这个省略号以为包只有两个版本这是一个很常见的误解。2.2 排查链路的第一步先别急着改 composer.json遇到这个报错我建议按下面的顺序快速过一遍通常能解决八成问题确认 PHP 版本和已加载扩展。运行php -v、php -m看看是否就是你预期的环境。如果是多版本 PHP 并存确认终端里用的是哪一个。运行composer diagnose。它会对 PHP 版本、JSON 扩展、网络连接、Git 配置等做一系列检查。如果提示某一行异常先解决它再继续。确认包名没有拼错。Packagist 对大小写敏感比如phpunit/phpunit不能写成phpunit/PHPUnit。可以直接去 packagist.org 搜索确认。确认版本约束本身写对了。^、~、*和dev-xx的语义差异巨大写错会导致约束无解。这一步的核心是先收集证据再动手改。我见过太多人一上来就删掉依赖版本号结果装出来的包版本号和隔壁组完全不一致最后线上炸了才追悔莫及。2.3 用 composer why、prohibits 和 why-not 定位冲突源如果根项目直接声明的依赖本身没有冲突但报错里出现了第三方包互相要求的情况就需要反向追踪了。Composer 2 提供了几个非常好用的定位命令。composer why vendor/package查一下已安装的包中是谁依赖了 vendor/package。比如composer why guzzlehttp/guzzle会列出所有依赖它的包及版本约束。composer prohibits vendor/package 2.0模拟如果我要把 vendor/package 升级到 2.0会是谁拦住我。composer why-not vendor/package 2.0输出拦截方和具体版本约束比prohibits的展示更清晰。举个真实场景你的项目需要foo/bar的 2.0 版本但foo/bar 2.0要求baz/qux ^1.0而另一个包foo/baz-wrapper要求baz/qux ^2.0。运行composer why-not baz/qux 1.0Composer 会把这条链完整列出来你立刻就能看到是谁在需求冲突的一端。2.4 解决冲突的四种策略以及各自的代价定位到冲突源之后有几个处理方向调整版本约束范围。把顶级依赖的约束放宽比如从foo/bar: ~1.2改成foo/bar: ^1.2 || ^2.0给求解器更大的空间。前提是得确认第三方包确实有兼容这两个版本的版本存在。升级或降级另一端的包。冲突往往不是发生在你要装的包身上而是它和其他包互相制约。找出那棵依赖树里可以移动的结点用composer update foo/baz-wrapper --with-dependencies单独升级某个包。利用 replace 和 provide。如果你维护 fork 包或项目内部用私有包替换了某个公共包的子依赖可以在 composer.json 里声明replace字段。这是比较高级的玩法但也容易引发我明明装了 A代码里却猜不到 A 的版本的问题要有心理准备。临时绕过。用--with-all-dependencies让 Composer 在更新时对其他包也放宽解析或使用--ignore-platform-reqs跳过平台条件。这两种方式都能让安装继续但都只是推迟问题不是解决问题。尤其--ignore-platform-reqs我建议只在 CI 构建和容器打包阶段使用后面第三章单独讲。3. Composer 的平台检查当 dependencies require 撞上你的 PHP 环境热词里有一句很典型composer detected issues in your platform: your composer dependencies require...。这其实对应的是 Composer 2 在安装完成后执行的平台检查或者依赖解析时的平台约束判断。它的本质是Composer 不仅仅检查包之间的互相依赖还要检查当前运行环境是否满足这些包对环境的要求。3.1 它到底在检查什么Composer 平台检查的对象有三类PHP 版本比如php: 8.1。PHP 扩展形如ext-mbstring、ext-openssl、ext-pdo只要包声明了这些依赖就要求当前 PHP 进程加载了对应扩展。系统库形如lib-curl、lib-iconv通常通过 PHP 版本绑定和编译配置判断。在解析依赖时这些条件都会被当成普通的依赖约束参与求解。比如laravel/framework声明了php: ^8.1和ext-mbstring: *那么安装它的前提就是你当前的 PHP 是 8.1 以上且开了 mbstring。判断有没有加载某个扩展最直接的方法是php -m它会列出所有编译加载的模块。如果在终端里列出来的和你 Web 服务里跑的 PHP 不一致那属于用错了 PHP不是 Composer 的问题。我遇到过一个同事排查了半天最后发现他composer用的 PHP 是/usr/bin/php7.4而 nginx/php-fpm 用的是另一个版本的 8.1服务器上有两套 PHP 并存这就是平台检查意义上最常见的坑。3.2 用 config.platform 声明目标运行环境有一种情况很微妙本地开发用 PHP 8.3而生产服务器还是 PHP 7.4。如果你直接在本地跑composer install解析出的依赖版本会以 8.3 为基准可能选到一些要求 PHP 8.0 的包。等你把同样的 composer.lock 带到服务器上结果就是装不上或者装上了运行直接白屏。Composer 提供了config.platform来解决这个开发和线上版本不一致的问题composer config platform.php 7.4.40这行命令会在 composer.json 的config.platform下写入php: 7.4.40。之后 Composer 在解析依赖时会假装当前平台是 PHP 7.4.40从而选出一套在 7.4 上能跑的版本组合。要注意platform.php只影响依赖解析不会改变你实际运行时的 PHP 进程版本。如果你的本机真的是 8.3锁定了一个为 7.4 解析的依赖组合其中某些包可能用了 PHP 8 的语法运行时依然可能出问题。所以它解决的是依赖选型问题不是运行环境问题。另外config.platform还可以指定扩展比如composer config platform.ext-mbstring 1.0模拟即使本机没装 mbstring 也能解析出需要它的包版本。但这里我的建议是扩展层面尽量实际安装不要只做模拟不然后续跑业务代码还是会挂。3.3 --ignore-platform-reqs 是张遮羞布用的时候要知道代价--ignore-platform-reqs会忽略所有平台相关的依赖约束包括 PHP 版本和扩展要求。在容器构建、CI 打包这类场景里它经常被拿来先装上再说。但它真的只是遮羞布。装上一个需要ext-redis的包而镜像里没有这个扩展最终运行时Call to undefined function Redis::connect()这种错一定会找上门。我见过最离谱的一次是别人在 Dockerfile 里对composer install加了--ignore-platform-reqs结果容器跑起来之后 php-fpm 加载PhpRedis相关的业务代码直接 fatal error整个服务挂了半个多小时。如果你必须在无扩展环境下完成依赖安装我建议至少做三步在composer install时用--no-dev避免 dev 依赖带来额外平台负担。安装完成后在真正的运行环境里执行composer platform-check让 Composer 自动扫描已安装包的环境要求并进行核对。在 CI 流水线里增加一个步骤检查composer platform-check是否通过通不过就让流水线失败。platform-check这个命令相当于是对遮羞布的兜底补偿让一次性错误变成自动化检查的一部分这也是我能接受的唯一一种--ignore-platform-reqs用法。4. 下载依赖慢与失败镜像仓库、缓存与 prefer-dist 的调优“卡在 Loading composer repositories 半天”“Downloading 总是失败”“明明指定了版本却装了个旧包”这类问题基本都集中在网络和缓存两个层面。这一节我把我实际调优过的方案全部列出来。4.1 慢的根源在哪Composer 的安装过程有两处网络请求请求仓库元数据对应Loading composer repositories with package information。下载包本体对应Package operations阶段的Downloading。默认 Packagist 和 GitHub 的访问速度在国内很不可控尤其是小水管服务器上拉一个大点的包集可能要几分钟。除了网络还有一个隐蔽因素Composer 1 时代没有并发下载需要靠hirak/prestissimo插件才能并行拉包Composer 2 原生支持并发下载大幅改善了下载阶段但元数据请求如果指向海外依然可能很慢。4.2 换镜像本质是换仓库源最好的解决办法是配置国内可用的 Composer 镜像仓库把默认的 Packagist 指向一个离你更近的服务composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/配置完可以用composer config -gl查看全局配置确认是否生效。这里的-g是写入全局去掉则写入当前项目。团队项目里我建议写进项目级配置并把改好的 composer.json 提交到版本库保证所有人一致。换镜像之后Loading composer repositories的耗时通常会从几十秒降到一两秒。注意这个操作改的是获取包信息和包文件的来源不会改变包的版本解析逻辑。部分私有包如果只存在于自己的 Git 仓库你还需要把repositories里配置的 VCS repo 一并写好它们会与镜像源并存。4.3 缓存机制拿到旧包的第一嫌疑对象Composer 在本机有缓存目录按平台不同通常在Linux/macOS~/.cache/composer/Windows%LOCALAPPDATA%\Composer缓存里存的是下载好的包压缩包files 目录和元数据中间结果。正常情况下这是好事第二次安装能省流量。但如果你改了版本约束或者你用的仓库元数据已经被更新Composer 的缓存可能让你以为装的是新版本其实还在用旧元数据。这时候优先执行composer update --no-install它会让 Composer 重新拉取一次元数据并更新 lock 文件内容不实际安装通常能刷新缓存判断。如果还不行再考虑composer clear-cache。但要注意clear-cache是核弹清完所有项目都要重新下载建议只在确定元数据异常时使用。另外shell 环境变量COMPOSER_MEMORY_LIMIT也比较常被忽略。依赖很多的项目在解析阶段可能内存吃紧出现Composer ran out of memory可以设成COMPOSER_MEMORY_LIMIT-1让它不限制或设置一个较大的值比如512M。4.4 prefer-dist 与 prefer-source一个是下载一个是克隆Composer 获取包有两种方式dist 和 source。dist从仓库下载压缩包快、体积小是默认推荐方式对应输出里的Downloading。source直接克隆 Git 仓库对应输出里的Cloning适合需要修改包源码调试的场景。默认配置是prefer-dist这没问题。但有的包在 dist 下载失败时Composer 会自动回退到 source 方式导致安装过程突然开始git clone非常慢。如果你在 CI 环境遇到这种问题可以用--prefer-dist强制只用压缩包减少意外。还有一个小技巧在电脑本地调试第三方包时可以临时用--prefer-source这样能拿到完整的 Git 历史方便git bisect定位包里的问题。调试完再改回默认。5. composer.lock 的工程价值一次线上回滚事故的复盘如果说前三章解决的是装不上的问题这一章解决的是装出了灾难的问题。composer.lock的重要性我只讲一个真实案例。之前有个项目同事在服务器上跑部署脚本里面写的是composer update --no-dev。结果某天一个第三方包发布了新版本和线上 PHP 7.4 环境不兼容部署后整个线上服务挂了。回滚时发现没有备份 lock 文件也没有备份 vendor 目录只能对着 git 历史慢慢猜之前用的版本折腾了快两个小时。从那以后我在所有团队的部署规范里都强制执行一条部署环境永远只准跑 composer install不准跑 composer update。5.1 lock 文件是怎么工作的composer.lock记录了当前项目在特定时刻经过求解后的完整依赖版本清单包括每个包的确切版本、来源、哈希和依赖关系信息。它和 composer.json 的关系是composer.json 声明我愿意接受哪些范围的版本。composer.lock 锁定这次实际安装了哪些具体版本。只要 lock 文件存在且与 composer.json 的 content-hash 匹配composer install就会严格按 lock 里的版本安装不会重新求解。这保证了开发、测试、生产三套环境的依赖完全一致。composer update则重新读取 composer.json 进行求解并生成新的 lock 文件。lock 文件里有一个字段叫content-hash它根据 composer.json 的 require 等配置生成。每次改动 composer.json这个哈希就会变化。如果你改了 composer.json 却忘了执行composer update再跑composer install时 Composer 2 会警告 lock 文件与 composer.json 不同步并提示运行composer update --lock来更新哈希。5.2 线上部署的标准动作我目前在 CI/CD 里使用的 Composer 命令基本固定composer install --no-dev --prefer-dist --no-interaction --no-progress --optimize-autoloader参数意义--no-dev跳过 require-dev 里的包生产环境不装调试工具。--prefer-dist优先压缩包下载避免 git clone。--no-interaction避免任何交互式提问导致部署脚本挂起。--no-progress减少日志输出Log 采集更干净。--optimize-autoloader把 PSR-4 和 PSR-0 映射转成 classmap提升生产环境自动加载速度。如果你需要对上一版本进行快速回滚最稳妥的是带上 lock 文件一起回滚然后重新执行composer install。vendor 目录不需要提交到版本库但 lock 文件一定要提交。5.3 什么时候才应该执行 composer update很多团队把composer update当成普通升级动作每次开发前都敲一遍这是最破坏可复现性的习惯。我更推荐的流程是用composer outdated查看有哪些包可以更新。明确本次要更新哪些包优先使用composer update vendor/package vendor/package2 --with-dependencies只更新选定目标及其依赖避免一次把所有包全部升级。更新前先确认 lock 文件有提交或备份一份。更新后跑完测试用例再合并代码。如果确实需要全量更新也建议在独立分支上进行生成的新 lock 文件经过测试再合入主干。全量composer update在版本约束很宽松的项目里往往会带来意料之外的惊喜。5.4 lock 文件过期不是小事前面提到composer install遇到 lock 过期Composer 2 会给警告“Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run composer update to update the lock file.”很多人忽略这个警告直接继续结果就是lock 里的版本和 composer.json 的声明脱节。比如你把phpunit/phpunit从^9.0改成了^10.0但 lock 还是旧的 9.x 版本install 依然会装 9.x而你还以为自己在用 10.x。正确做法是只要改动了 composer.json 中的 require 或 require-dev就尽快执行composer update --lock或composer update 对应包名确保 lock 与 composer.json 同步。composer update --lock这个命令很实用它只更新 lock 文件的 content-hash不改变已锁定的版本适合我只调整了配置但不打算此时升级包的场景。6. 最后再分享几个我踩过的 Composer 坑前面每一章都带了排错思路最后我再补充几个实操中容易被忽略的细节算是我这几年和 Composer 打交道积累下来的碎碎念。第一个是磁盘空间。composer install下载的 dist 包会先解压到临时目录再移动到 vendor。如果服务器/tmp所在分区空间不足会出现“Not enough memory”或者解压失败但报错信息不一定很明显。检查时记得用df -h看看 /tmp 和项目所在分区别光盯着内存。第二个是多目录项目里的多份 lock。有的项目拆成多个子目录每个子目录各有一套 composer.json却没有统一脚本管理。这种情况下漏更新某一个子目录的 lock部署时就会装出不一致的依赖。我建议在 CI 里对所有子项目的 lock 都做完整性校验至少让composer install --dry-run跑一遍。第三个是包的版本号带不带 v 前缀。有些标签在 GitHub 上叫v1.0.0但 Packagist 展示时通常不带 v写约束的时候用1.0.0而不是v1.0.0。如果你写v1.0.0作为精确版本有时会解析到一个奇怪的 dev 分支导致行为不符合预期。第四个是改了代码不生效先怀疑 opcache再怀疑 autoload。很多人部署完新代码发现还是旧逻辑第一反应是缓存问题。但如果你在composer install或composer dump-autoload时用了--classmap-authoritative又刚好改了某个类的位置旧的 classmap 可能被 CDN 或 opcache 缓存住。这种情况建议重新执行composer dump-autoload -o并确认 PHP-FPM 的 opcache.validate_timestamps 配置合理。这些坑单看都不大串在一起却能消耗一个下午。Composer 的最大价值不是帮你“装上包”而是让你能精准控制“装哪些版本的包”。理解它每一步在做什么遇到问题才能不慌。