2.7 Composer 与包管理：站台物资采购处

2.7 Composer 与包管理：站台物资采购处

本节摘要：现代 PHP 开发是"组装"而非"自造"：日志、HTTP 客户端、支付 SDK 都有现成库，Composer 负责采购、版本协调与装载。本节讲依赖声明的写法与版本约束的含义、自动加载的原理、install 与 update 的分工，以及锁文件为何必须进版本库。读完你应当能独立为项目引入第一个第三方库，并理解"为什么同事跑完安装一切正常、我这却报错"这类经典纠纷。

手动引用类文件的末路

没有包管理器的年代，引入一个库意味着下载压缩包、解压、在业务代码里 require 一串类文件。两三个库还撑得住，十个库立刻出现三重灾难：重复引入（A 库和 B 库各带一份同名工具类）、版本冲突、升级靠手工替换文件。Composer 把这三件事全部接管：集中声明要什么，它去解析各库之间的依赖关系图，装回一套互不冲突的版本，再提供统一的自动加载入口——月台物资不再各带各的，全走一个采购处。

采购流程：声明、安装、装载

在项目根目录初始化并引入第一个库（以日志库为例）：

composer init        # 生成 composer.json，交互式填写项目名与依赖（也可跳过手写）

composer require monolog/monolog
# 运行后会发生三件事：
# 1. composer.json 里多了一行依赖声明
# 2. 生成（或更新）composer.lock，锁定精确版本
# 3. 依赖实体装进 vendor 目录，自动加载器就位
​

业务代码里从此只需要一行装载：

<?php
require __DIR__ . '/vendor/autoload.php';   // 全项目唯一的手工 require

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('station');
$log->pushHandler(new StreamHandler(__DIR__ . '/logs/app.log', Logger::WARNING));

$log->warning('3 号月台排队偏长');           // 落盘一行警告
$log->error('寄存库连接失败', ['retry' => 2]);
​

use 语句import类名，自动加载器按命名空间映射找到类文件并按需加载——你没写任何 require，类却"随用随到"。这套机制依据的是社区约定的命名空间到目录的映射规范（PSR-4），自己的类同样能纳入：

{
    "name": "station/core",
    "require": {
        "php": ">=8.1",
        "monolog/monolog": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "Station\\": "src/"
        }
    }
}
​

改完这段声明执行 composer dump-autoload，之后 src/ 目录下的 Station\TicketService 类（文件为 src/TicketService.php）即可随用随载。目录即命名空间、文件即类名，这个纪律守住了，自动加载就永远不会失灵。

图：依赖树的形状——你的项目只是根节点

版本约束与两条命令的分工

版本约束是采购处的"行话"，两个符号最常用：^3.0 表示 3.x 区间内可升级（装 3.5、3.9 都行，不会跳到 4.0 破坏兼容）；~3.4 更保守，只允许补丁位变动（3.4.x）。直接写死 3.5.2 一般只在排查兼容性时临时使用。

两条命令的分工必须分清，这是"同事机器正常我这报错"的根源：

口径一句话：install 是"按单收货"，update 是"重新询价"。部署环境只跑 install；update 是开发机上的决策动作，做完连同更新后的锁文件一起提交。锁文件（composer.lock）务必进版本库——它是"全站物资版本一致"的唯一凭证，生产事故排查时第一条就是核对锁文件。

依赖升级的例行流程：把"更新"变成Routine

2.6 节的安全问答里埋了句话："很多线上事故是用着的第三方库爆了已知漏洞没升级"。这里把"升级"展开成可执行的例行流程，让它成为月台的月度保养项而不是救火动作：

例行盘点（每月一次，开发机上）：
  1. 列出过时依赖清单（composer outdated 命令），按"是否有安全修复"排序
  2. 有安全修复的：当周升级，锁文件提交，跑 2.8 测试集
  3. 无安全修复的常规更新：攒到版本窗口统一处理，逐个升级逐个验证
  4. 大版本跨越（如某库 3 到 4）：单独开任务，先读该库的升级指南再动手
​

流程里最有价值的是排序原则——安全修复插队，功能更新排队。多数依赖告警平台（对接包仓库的公告数据）都能给出"这个过时版本有没有已知漏洞"的判断，把这条信息接到盘点流程最前面，升级工作就自动聚焦到真正要紧的地方。另一个实践细节：每次升级用一次独立提交（只动锁文件与 json），出问题时可以精确回滚单次升级，而不是在一个月的混合提交里考古。

升级纪律与 2.8 的测试形成闭环：测试集是升级的"验收闸"，没有它，升级的验证只能靠手工点页面，例行流程很快会因为麻烦而被放弃——这也是很多团队依赖常年不动的真实原因。反过来，测试齐备的团队升级心态完全不同：跑一遍绿了就合并，依赖永远停在近版本，安全公告来了当天就能修。依赖卫生是测试价值的延伸战场，两者共同构成项目的长期可维护性底盘。

常见坑

⚠️ 把 vendor 提交进版本库：体积巨大且和锁文件重复，仓库里只放 json 与 lock 两个文件，vendor 每台机器自行 install。

⚠️ 盲目 composer update 图省事：无意间把全站依赖升到新版本，兼容性问题成批爆出——升级要有意、有单、有回归验证（正好接 2.8 的测试）。

本节要点回顾

• Composer 管三件事：解析依赖树、锁定精确版本、提供自动加载，物资采购从此一个窗口。
• 自动加载零 require：引入装载器一行，之后按命名空间随用随载，自己的类用 PSR-4 约定纳入。
• 版本约束两符号：^ 主版本内升级，~ 更保守的补丁位升级，写死版本仅排查用。
• install 与 update 分工：部署按锁文件 install，升级在开发机 update 后提交新锁文件。
• 锁文件必进库：它是全站依赖一致的唯一凭证。

下一节是质检岗：测试。物资与代码都要在发车前过一遍例行检修。