一个小项目要加日志功能,本地执行 composer require monolog/monolog,代码跑得挺好。上线时把整个项目打包传服务器,包括 vendor 目录。结果线上 500,日志里一行 Class "Monolog\Logger" not found。文件明明都在,类就是找不到。

第二次学乖了,把 vendor 加进 .gitignore,部署时直接在服务器上跑 composer install。测试环境好了,线上又报另一个错:某个包要求 PHP 8.3,服务器还是 8.2。第三次才发现,本地能装、线上装不了,是因为 composer.lock 早就被忽略掉了。

Composer 是 PHP 的依赖管理工具,但它解决的问题不止「下载库」。这篇讲清楚它到底管什么、json 和 lock 各是什么、版本约束怎么写、install 和 update 有什么区别、自动加载怎么工作,最后用一个接日志库的完整过程把这些串起来。

Composer 到底做了什么

四件事,按发生顺序:

声明你在 composer.json 里写「需要哪些包、什么版本范围」,这是人的意图。
解析Composer 把所有包的依赖关系算一遍,找出同时满足所有约束的一组具体版本。这一步常常会冲突。
锁定解析结果写进 composer.lock,记录每个包的确切版本和下载地址。之后所有人装的是同一套。
安装与自动加载把包下载到 vendor,生成 vendor/autoload.php。所有类通过它按需加载,不用手写 require。

很多人把 Composer 当成「下载器」,只用 require 命令,忽略了后面三步。真正让项目可复现的是 lock,真正让代码能跑的是 autoload。

Composer 2 是当前主流版本,速度和内存都比 1.x 好很多。它需要 PHP 7.2 以上,跟项目本身的 PHP 版本要求是两回事。

composer.json 与 composer.lock

两个文件的分工,是理解 Composer 的关键:

文件内容谁改要不要提交
composer.json你声明的依赖范围、自动加载配置、脚本人手动改,或 composer require 自动追加必须提交
composer.lock解析出的每个包的确切版本、哈希、来源只有 composer update 会改应用项目必须提交;库项目按团队约定
vendor/下载下来的包和生成的 autoload 文件Composer 自动生成不提交,部署时安装

composer.json 里的版本范围是「意图」,lock 里是「这次实际选中的结果」。把 lock 提交进版本库,测试、预发、生产才能装出完全一样的依赖。把 lock 忽略掉,每次 composer install 都相当于重新解析一遍,今天装 1.2.3,下个月装 1.3.0,问题可能就在某个补丁版本里出现。

composer.lock 冲突时不要随手删掉重新生成。删掉等于放开所有版本约束,CI 可能装出一套没人验证过的依赖。正确做法是拉取最新分支,在本地执行 composer update --lock 或按冲突逐个解决,确认依赖树后再提交。

真实的冲突处理顺序是这样的。两个人各加了一个包,合并时 lock 里冲突的往往不是版本号那一行,而是 content-hash 和整段 packages。先解决 json:把两边的 require 都保留,然后本地执行 composer update --lock,它只重算哈希和锁文件结构,不动已经锁定的版本;如果解析时报冲突,按报错逐个处理,用 composer why-not 查是谁挡住了某个版本。最后跑测试,提交新的 lock。

这个过程最忌讳两件事:删掉 lock 重新生成,以及直接选「接受对方的 lock」。后者会把自己这边的依赖悄悄丢掉,CI 一装就少一个包,而本地的 vendor 还在,谁都不会立刻发现。

版本约束:^ 和 ~ 到底什么意思

版本号遵循「主.次.补丁」的语义化版本(SemVer)。主版本变化一般意味着不兼容,次版本加功能,补丁修 bug。Composer 的约束符号就是围绕这个约定设计的:

写法等价范围说明
1.2.3只有 1.2.3精确锁定,最稳也最死
^1.2.3>=1.2.3 且 <2.0.0允许次版本和补丁升级,不允许主版本变
~1.2.3>=1.2.3 且 <1.3.0只允许补丁升级,范围更窄
1.2.*>=1.2.0 且 <1.3.0通配符,效果接近 ~
^1.2>=1.2.0 且 <2.0.0省略的位数按 0 补齐

最常用的是 ^,因为它默认相信「主版本不兼容」这个约定。~ 适合那些次版本也会破坏兼容的包,比如某些框架的小版本升级会改行为。精确版本适合内部私有包,或者你正在排查某个版本引入的 bug。

约束写得太松,一次 update 可能带进一堆新行为;写得太死,安全补丁也升不上去。折中的做法是:日常用 ^,把 lock 提交,定期单独做一次升级并跑测试。不要在生产发布前临时 composer update。

require-dev 里的包只用于开发和测试,比如测试框架、静态分析工具。部署时加 --no-dev 可以跳过它们,减少体积和攻击面。反过来,把测试工具写进 require,生产环境也会装上一堆用不到的东西。

版本约束还有一个隐含维度:稳定性。Composer 默认只接受 stable 版本,某个包只有 beta 或 dev 时,要在约束里显式写 @beta 之类的标记,或者调整 minimum-stability。团队里如果有人本地改了这个设置,别人 install 时可能拿到不同的解析结果,最终还是要以 lock 为准。

install 与 update:只差一个词,后果完全不同

两条命令很像,行为差别很大:

composer install

按 composer.lock 安装。lock 存在时完全照它来,不会升级任何包。日常拉代码、CI、部署都应该用它。

composer update

重新解析依赖,按 composer.json 的约束选最新可用版本,并改写 lock。它会升级依赖,属于「主动变更」,需要测试。

几个常用参数:--no-dev 跳过开发依赖;-o(或 --optimize-autoloader)把 PSR-4 映射转成 classmap,减少运行时的文件查找;--classmap-authoritative 更激进,完全按 classmap 加载,适合生产但要求 classmap 完整;--no-scripts 跳过脚本,排查问题或部署受限时用。

composer dump-autoload 只重建自动加载文件,不下载包。新增了类、改了命名空间、或者用了 autoload.files 之后,需要执行它。部署脚本里经常漏这一步,表现是「文件明明在,类就是找不到」。

脚本(scripts)是另一个容易出事的点。post-install-cmd、post-update-cmd 里常挂着「清理缓存」「生成配置」这类命令,装依赖时自动执行。好处是省一步操作,坏处是它会在你没预期的时候动文件,而且某些命令依赖项目的运行环境。部署到只读文件系统、或者数据库还没迁移完时,脚本一跑就失败,整次安装中断。所以很多团队在生产部署时加 --no-scripts,把该做的事写进发布脚本,按自己的顺序执行,而不是交给 Composer 隐式触发。

真实的一次事故更能说明问题。部署脚本写的是 composer install --no-dev && php-fpm reload,服务器磁盘只剩两百兆,装到一半报 write failed,install 以非零退出,&& 让重启那一步确实没执行,可流量已经切到了这台机器。旧的 release 目录被覆盖了一半的 vendor,autoload 还是上一版,于是同一个接口刷新几次,有时正常、有时 Class not found。这种「时好时坏」基本就是装了一半的特征:先看 vendor/composer/installed.json 的修改时间和包数量,再用 composer show 对一遍,缺哪个包一眼就能看出来。正确的部署是把依赖装在独立目录、装完再原子切换,而不是就地覆盖正在服务的文件。

--no-scripts 也不是万能药。它只跳过钩子,包该装的还是装,autoload 该生成的还是生成;如果你的发布流程依赖脚本里的「生成配置」「清理缓存」,加了它就必须自己补上这两步,否则会出现「依赖齐了但配置没生成」的新问题。

自动加载:PSR-4 是怎么把类找到的

PSR-4 是一条命名空间与目录的映射规则:命名空间前缀对应目录,类名对应文件名,大小写敏感。在 composer.json 里这样写:

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

于是 App\Order\OrderService 会被映射到 src/Order/OrderService.php。文件名必须和类名完全一致,包括大小写。Windows 和 macOS 默认文件系统不区分大小写,本地怎么写都能找到;Linux 服务器区分,orderService.php 和 OrderService.php 是两个文件。这是「本地好好的,线上 Class not found」最常见的原因。

自动加载的工作方式是:require 'vendor/autoload.php' 注册一个加载器,代码第一次用到某个类时,PHP 触发加载器,加载器按映射找到文件并引入。整个过程是懒加载,没用到的类不会被读进来。

如果项目里有些函数而不是类,PSR-4 管不到,可以用 autoload.files 声明,Composer 会在启动时直接引入这些文件。代价是每次请求都会加载,文件多了会影响启动时间,能写成类就写成类。

composer dump-autoload -o 会扫描所有 PSR-4 目录,生成一个「类名到文件」的静态表。线上开着 OPcache 时,这个表解析很快。类的数量不多时收益有限,但它是部署的标准动作之一。

老项目里常有一段不符合命名空间的代码,比如 legacy/ 下面一堆 class Foo_Bar {},既没有 namespace,文件名也不对。这类代码塞不进 PSR-4,但可以整体映射成 classmap:在 autoload 里写 "classmap": ["legacy/"],Composer 会扫描目录、解析出里面所有的类和接口,生成映射表。它不需要改名,代价是新增文件后必须重新 dump-autoload,否则新类不认。混用 PSR-4 和 classmap 是迁移期的正常状态,不要为了「统一」把几万行老代码一次性改名重排。

classmap 有个容易踩的边界:加了 --classmap-authoritative 之后,Composer 不再回退到 PSR-4 查找,classmap 里没有的类直接判为不存在。老项目里如果有 eval、模板拼类名、或者运行时才生成的类,扫描阶段找不到,线上就报 Class not found,而本地没开这个参数一切正常。开启前先确认没有这类动态类,不确定就用 -o 够了。

场景走查:给项目接一个日志库

需求:把散落的 error_log() 换成结构化日志,按天切文件,能记录上下文。选 Monolog,它符合 PSR-3 日志接口。

第一步,本地执行 composer require monolog/monolog。Composer 会下载包、更新 composer.json 和 composer.lock、重建 autoload。代码里直接 new Logger('app') 就能用,不需要手写 require——这是自动加载在起作用。

第二步,提交 composer.json 和 composer.lock,不提交 vendor。同事拉代码后执行 composer install,装到的版本和你完全一致。

第三步,部署脚本里加两行:composer install --no-dev -o 和 php artisan ... 之类清理缓存的动作(没有框架就省略)。如果服务器不能连外网,就在 CI 里构建好 vendor 作为产物,再传到服务器;而不是在服务器上现场下载。

第四步,第一次上线就撞了墙:服务器 PHP 8.2,本地 8.3,Monolog 的某个新版本要求 8.3,composer install 直接失败。解决办法是在 composer.json 里加平台配置,让本地解析时按线上的 PHP 版本来:

{
  "config": {
    "platform": {
      "php": "8.2.0"
    }
  }
}

加上之后执行 composer update --lock,让 lock 按 8.2 重新解析。这个配置的意义是「假装我在 8.2 上」,避免本地选了线上装不了的版本。它不会改变实际运行环境,只影响解析。

最后,把 vendor/ 加进 .gitignore,部署日志里记录本次安装的包版本。上线后日志正常写入,才算真正完成。

真正麻烦的是第二次发布:只改了 composer.json,加了一个新包和一个 PSR-4 目录,忘了在本地跑 update,lock 还是旧的。本地手动执行过 dump-autoload,类能找到;提交后 CI 执行 composer install,先打一条 Warning: The lock file is not up to date with the latest changes in composer.json...,然后继续按旧 lock 安装——新包根本没装,新目录也没进自动加载。上线后,只有新代码用到的那个类直接 Class not found,堆栈指向 new 那一行,而文件明明就在仓库里。

定位按固定顺序走。第一步 composer validate,它会把「lock 与 json 不一致」明确报出来,比在几千行日志里找 Warning 快。第二步 composer show 看实际装了哪些包,和 composer.lock 里写的对一遍;如果怀疑线上装成了另一套,用 composer show --locked 列出锁文件里的包,再和 vendor/composer/installed.json 比,差异就是真实被替换或漏装的部分。第三步,想知道某个版本为什么没装上,用 composer why-not vendor/package 1.2.3,它会打印是哪条约束挡住了。跨机器排查时直接 diff 两边的 composer.lock 最快,哪怕只有 content-hash 一行不同,也说明依赖树不是同一份。

本地验证三步,每步都有明确的通过标准。第一,composer validate --no-check-publish,本机实测输出 ./composer.json is valid, but with a few warnings(缺 license 等元数据会有警告,加 --strict 会以非零退出),lock 过期会额外报一条。第二,composer install --dry-run,看到 Nothing to install, update or remove 说明 vendor 与 lock 一致,出现 Installing 列表就说明有东西没装。第三,php -r "require 'vendor/autoload.php'; echo App\Order\OrderService::class, PHP_EOL;",能打印出完整类名而不是 Class not found,才算自动加载覆盖到了新目录。

现象、原因与第一步

现象真实原因第一步查什么
Class not foundvendor 没装、autoload 没重建,或命名空间与目录不符确认 vendor/autoload.php 被引入;执行 composer dump-autoload
本地正常,线上报错lock 没提交、没执行 install,或 PHP 版本/扩展不同对比两边 composer show 的版本,确认 lock 是否在版本库
安装时版本冲突两个包对同一个依赖的约束不相容用 composer why-not 包名 版本 看谁在阻止
升级一个小版本后全站坏直接在生产执行了 composer update回滚 lock 并重新 install;在测试环境复现后单独升级
部署卡在下载依赖服务器不能访问外网或镜像源改为 CI 构建产物,或配置可用的镜像/私有仓库
生产装了测试框架部署命令漏了 --no-dev看部署脚本和 vendor 里的包列表
类名大小写不一致时好时坏Linux 文件系统区分大小写,本地不区分核对文件名与类名,统一用 PascalCase
改完 autoload 配置不生效只改了配置,没重新生成加载文件执行 composer dump-autoload;确认命令在部署流程里

边界与代价

依赖越多,升级和审计的成本越高。每加一个包,就多一份代码要跟着 PHP 版本升级、多一个可能的安全漏洞来源。引入前问三个问题:这个功能自己写要多少行、这个包最近一年有没有维护、它的依赖树有多深。

lock 冲突是团队协作的常态。两个人同时改依赖,锁文件的哈希和版本段落会冲突。不要用「删了重装」解决,那会让整棵依赖树漂移。正确顺序是:合并 json、在本地重新解析、跑测试、提交新的 lock。

私有包需要凭证配置。凭证不要写进 composer.json,用环境变量或全局 auth.json,并且确认它不在版本库里。CI 里用只读令牌,别用个人长期令牌。

Composer 不是部署工具。它不会帮你切流量、回滚、清理缓存。把「安装依赖」当成发布流程的一步,而不是发布本身。

还有一件常被忽略的事:依赖里的已知漏洞。composer audit 会按 lock 里的版本对照公开的漏洞库,列出受影响包和建议的修复版本,有漏洞时返回非零退出码,所以可以直接挂进 CI。它不能替你判断「这个漏洞在不在我们的调用路径上」,很多漏洞只在特定用法下可利用,报出来不等于必须立刻升,但不看肯定不行。比较实际的节奏是:每次发布前跑一次,出现高危的先评估,能升就升,升不动就确认代码里没有触发那个入口,并在下一次迭代里安排。

具体怎么评估一条高危报告:先看它影响哪个函数或入口,再在代码里搜这个入口有没有被调用,没调用可以暂时压后,但要记一条待办。再确认它是直接依赖还是间接依赖,composer why vendor/package 会打印引入链;很多漏洞包是某个 SDK 拖进来的,升 SDK 比单独钉住子包更安全。能升就只升这一个:composer update vendor/package --with-dependencies,不要顺手 update 全量。升完再跑一次 composer audit,退出码回到 0 才算这一项关闭。

当天能自己验证的练习

  1. 新建目录,执行 composer init,手动加一条 psr-4 映射,写一个类,用 composer dump-autoload 后确认能直接 new。
  2. 把类文件名改成小写,在 Linux 环境或容器里访问,观察是否报 Class not found。
  3. 执行 composer require psr/log,查看 composer.lock 里记录的版本和来源,再把 lock 删除后 install,对比两次结果。
  4. 用 composer show --tree 查看依赖树,找一个间接依赖,理解它为什么会被装进来。
  5. 在 composer.json 加 config.platform.php 为 8.2.0,执行 composer update --lock,看看哪些包的版本被降下来了。

小结

三句话:json 写意图,lock 记结果,两者都要提交;日常用 install,升级才用 update,生产永远别临时 update;autoload 靠 PSR-4 映射,文件名和类名大小写必须一致。

下一篇讲数据库。有了 Composer 和自动加载,才能方便地引入数据库工具、组织仓储类;但真正决定查询快慢和安不安全的,是 PDO 怎么用、SQL 怎么写。下一篇会从一个「本地 0.1 秒、线上 3 秒」的列表页开始,讲到预处理语句为什么能挡住注入。