Composer 不只是「装包的」
很多个人站长第一次接触 Composer，是在部署一个开源 PHP 项目时，按文档敲下 composer install，然后看着屏幕滚过一堆下载日志。装上能跑，也就到此为止了。但真正把 Composer 用明白，是 PHP 站点运维里绕不开的一课：它决定了你的依赖能不能稳定重现、上线能不能原子回滚、生产环境会不会因为一个 composer.lock 不一致而白屏。
这篇文章从依赖声明、lock 文件的真正含义、autoload 机制、国内镜像加速，讲到生产环境的部署姿势和常见故障排查，目标是把「composer 装包」升级成一套可复现、可回滚、可审计的依赖管理流程。
composer.json 与 composer.lock 的分工
这是理解 Composer 的第一道坎，也是造成最多生产事故的地方。两个文件必须分清：
- composer.json：你手写的依赖「声明」，写的是版本约束，比如
"monolog/monolog": "^3.0"。它是意向，不是结果。 - composer.lock：Composer 解析约束后算出的「精确结果」，记录每个包的确切版本号和它的哈希。它是事实，应该提交进版本库。
两者的关系决定了两个命令的根本区别：
# install：严格按 lock 文件安装，lock 不存在或不匹配才去解析
composer install
# update：重新解析 composer.json 里的约束，升级包，然后改写 lock
composer update
# 只升级某一个包（推荐，避免全量升级引入意外变更）
composer update monolog/monolog生产环境永远用 composer install——它保证每台机器、每次部署装出来的依赖完全一致。开发机才会用 update。如果在生产环境误敲 update，可能一夜之间把几十个依赖包一起升级到未经测试的新版本，直接导致站点白屏。
版本约束：^ ~ * 到底差在哪
composer.json 里的版本号写法决定了 update 时能升到多远：
1.2.3精确锁定，只能装这个版本^1.2.3允许升级到1.x.x（不跨主版本），语义化版本里主版本变=可能不兼容，所以只在小版本和补丁版本内浮动。这是最推荐的写法~1.2.3允许补丁级浮动，约等于>=1.2.3 <1.3.0*任意版本，绝对不要在项目里用>=1.0 <2.0手写区间，适合约束不规范的包
这里有个容易误解的点：^0.3.5 对于 0.x 版本，允许升到 0.3.x 而不会到 0.4——因为语义化版本规定 0.x 属于不稳定期，所有小版本都可能破坏兼容。Composer 对此的处理是特殊的，出过不少「以为 ^0.3 会跟着升大版本」的踩坑案例。
autoload：Composer 真正给你的东西
很多人以为 Composer 只是下载文件，其实它最重要的产出是 vendor/autoload.php——一个统一的自动加载器。你只需要在入口文件里 require 'vendor/autoload.php'，之后所有命名空间类都能自动找到，不用手动 include。
Composer 支持四种自动加载方式，通过 composer.json 的 autoload 字段配置：
{
"autoload": {
"psr-4": { "App\\": "src/" },
"psr-0": { "Legacy_": "lib/" },
"classmap": ["database/seeds/"],
"files": ["src/helpers.php"]
}
}- psr-4：现代标准。
App\Foo\Bar自动映射到src/Foo/Bar.php，靠命名空间找路径，最推荐。 - psr-0：老标准，路径里带下划线和命名空间混合，现在基本只用于兼容老代码。
- classmap：Composer 扫描目录，把所有类名和文件路径登记成一张大表，查找快但新增文件必须重新
dump-autoload。 - files：每次请求都无条件 include 这些文件，用来放全局函数（如 Laravel 的 helper）。注意 files 里的文件不能定义类，只能放函数/常量。
改完 autoload 配置后必须重新生成加载表，否则新类找不到：
composer dump-autoload
# 生产环境用 -o 生成优化过的 classmap，查找更快
composer dump-autoload -o --no-dev国内镜像加速：告别龟速下载
Composer 默认从 packagist.org 拉包，国内服务器直连经常几 KB/s 甚至超时。切国内镜像能提速十倍以上。全局配置一次即可：
# 阿里云镜像（目前最稳定）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
# 查看当前全局配置
composer config -g --list
# 需要时换回官方源
composer config -g --unset repos.packagist如果是给单个项目配镜像，去掉 -g，会在项目目录下生成/修改 composer.json 的 repositories 字段。更彻底的做法是设 COMPOSER_HOME 环境变量指向一个固定目录，让所有项目共享同一份配置和缓存。
顺带提两个实用配置：COMPOSER_MEMORY_LIMIT=-1 解除内存限制（大项目 dependency resolution 很容易吃光 128M 的 PHP 内存限制）；composer clear-cache 在怀疑缓存损坏时清空下载缓存。
生产环境部署：--no-dev 与原子发布
开发依赖（PHPUnit、调试工具等）不应该装到生产环境。Composer 用 --no-dev 区分：
# 生产环境标准部署命令
composer install --no-dev --optimize-autoloader --no-interaction --no-progress
# 或只装指定阶段（Composer 2.2+ 的依赖分组）
composer install --no-dev --prefer-dist参数含义：--no-dev 跳过 require-dev；--optimize-autoloader（-o）生成 classmap 加速；--no-interaction 无人值守不提示；--prefer-dist 优先下压缩包而非 git clone（更快）。
配合「原子发布」目录结构（releases/ + current 软链），部署流程是：新目录里 composer install → 同步代码 → 切换软链。这样即使安装失败，线上仍是旧版本，不会出现半成品状态。绝对不要在 current 目录里直接 install，一旦中途出错站点就挂了。
vendor 要不要提交进 Git
这是新手最常见的纠结。结论很明确：不提交 vendor，但要提交 composer.lock。
- vendor 是外部依赖的产物，体积大、变化频繁，提交会让仓库爆炸、diff 无法阅读。
- composer.lock 是几十 KB 的小文件，记录了精确版本，提交它才能保证
install可复现。
配合上面的部署流程，每台机器用自己的 composer install 重建 vendor。唯一例外是一些无 SSH/无 Composer 的共享主机环境，那种情况下才会在本地 install 后打包 vendor 一起上传——但这属于妥协而非最佳实践。相应地，.gitignore 里写 /vendor/。
故障排查清单
Composer 的报错信息不总是友好，下面几个是最常见的情况：
- Your requirements could not be resolved：版本约束互相冲突。加
-vvv看详细的冲突链，或用composer why-not 包名 版本查「为什么不能装这个版本」。 - Class not found：90% 是改了 autoload 没
dump-autoload，或者命名空间大小写和目录不一致（Linux 区分大小写，Windows 不区分，本地正常线上炸）。 - lock file is not up to date with the latest changes in composer.json：你改了 json 没 update，或直接删了 lock。解决：跑一次
composer update --lock只更新 lock 的哈希而不动版本；实在拿不准就composer update 具体包。 - memory limit exhausted：
COMPOSER_MEMORY_LIMIT=-1 composer update，或调大php.ini的 memory_limit。 - could not be downloaded：镜像不通或被墙，切换镜像源、检查 DNS，或
composer clear-cache后重试。 - PHP 版本不满足：包要求
^8.1而你跑 8.0。composer check-platform-reqs能列出所有平台要求是否满足。
另外注意 Composer 2 与 1 的差异：Composer 2 用了并行下载和新的依赖解析器，速度快很多，但某些老包的无版本约束写法在 2 里解析结果可能和 1 不同。老项目升级 Composer 时要先在测试环境验证。
安全审计：composer audit
依赖包的安全漏洞是站点被入侵的常见入口。Composer 2.4+ 内置了审计命令：
# 检查已安装依赖是否有已知漏洞
composer audit
# 输出格式可选：--format=json / --format=plain / --format=summary
composer audit --format=json它会拿 lock 文件里的版本去比对安全公告库，列出受影响的包和建议修复版本。建议加进 CI 或每周的例行巡检。想更进一步，可以用 composer outdated --direct 看直接依赖里哪些落后于最新版，再决定升级节奏。切忌一次性全量升级到最新——依赖升级是「小步快跑 + 测试」，不是「一夜之间换血」。
Composer 的缓存与离线部署
Composer 下载过的包会缓存在本地（Linux 下通常在 ~/.cache/composer 或 $COMPOSER_HOME/cache），下次安装同样的包直接从缓存取，不再走网络。理解这一点对生产部署很有用：如果一个站点要部署到多台机器，可以先在其中一台把所有依赖拉全，再把 COMPOSER_HOME 目录（或整个 vendor + 缓存）同步过去，后续机器安装时几乎不需要联网。
# 指定自定义缓存目录（便于多机同步与清理）
export COMPOSER_HOME=/opt/composer-home
composer install --no-dev -o
# 缓存诊断：列出已缓存的包
composer cache-list
# 磁盘清理：清空下载缓存
composer clear-cache对于完全没有外网的生产机器，还可以用 composer install --prefer-offline，它会尽量只用缓存、只在缓存缺失时才联网，适合网络不稳定的环境。极端情况下用私有 Satis 或 Toran Proxy 自建私有 Composer 仓库，把依赖镜像到内网——不过对个人站长来说，前几种方式通常已经够用。
CI/自动化里的 Composer 姿势
如果站点有自动化部署脚本，Composer 步骤要写成「可重复、无人值守、失败即止」。一个稳健的部署片段大概是：
#!/bin/bash
set -euo pipefail
export COMPOSER_HOME=/opt/composer-home
export COMPOSER_MEMORY_LIMIT=-1
export COMPOSER_NO_INTERACTION=1
cd /srv/app/releases/$(date +%Y%m%d%H%M%S)
composer install --no-dev --optimize-autoloader --prefer-dist
# 校验依赖完整性，缺包立刻失败
composer validate --no-check-publish
# 上线前跑一次漏洞审计，高危可阻断发布
composer audit --format=plain || echo "有漏洞，请人工确认"set -euo pipefail 保证任何一步失败都停下，不会带着半成品目录切流量。composer 的退出码是有含义的：正常为 0，依赖解析冲突等错误为非零，所以能安全地串联进 shell 脚本。
检查清单：把自己的 Composer 习惯过一遍
- composer.lock 是否已提交进版本库？vendor 是否已 gitignore？
- 生产部署是否用
install --no-dev -o而不是update？ - 是否配置了国内镜像？是否设了
COMPOSER_MEMORY_LIMIT？ - autoload 是否用 psr-4 而不是 classmap 硬扫？改完是否记得
dump-autoload -o？ - 是否定期跑
composer audit检查漏洞？ - 部署是否走 releases 原子切换，而非在 current 里原地 install？
Composer 的价值不在「能装包」，而在于把 PHP 项目的依赖变成一份可复现、可审计、可回滚的声明。个人站长通常只有一个生产环境、没有完善的 CI，正因如此，更需要守住「lock 文件进版本库、生产只 install、上线走原子目录」这三条底线——它们能在你最狼狈的一次凌晨故障里救你一命。