学完这篇你能把 Composer 从「只会 composer require」用到能自己配自动加载规则、写清版本约束、把公司私有仓库拉进项目里。
第一步：搞清自动加载的三个入口
Composer 的自动加载全部写在 composer.json 的 autoload 段里，三种主流写法对应三类代码：
{
"autoload": {
"psr-4": {
"App\\": "src/",
"App\\Admin\\": "src/Admin/"
},
"classmap": ["legacy/", "lib/Old_Thing.php"],
"files": ["src/helpers.php", "src/constants.php"]
},
"autoload-dev": {
"psr-4": { "Tests\\": "tests/" }
}
}
- psr-4：新代码用这个。
App\Foo\Bar 会自动映射到 src/Foo/Bar.php，一个前缀可以配多个目录（用数组）。
- classmap：老项目、下划线命名、一个文件多个类的代码用它，Composer 会扫描目录生成类名→文件路径的静态表。
- files：纯函数、常量定义用这个，每次请求都会 include，别放重的逻辑。
改完 autoload 段必须执行一次：
composer dump-autoload # 重新生成 vendor/composer/autoload_*.php
composer dump-autoload -o # 生成 classmap，生产环境用
composer dump-autoload -a # --classmap-authoritative，只信 classmap，不再走文件系统查找
-a 在线上最值得开：类找不到就直接报错，不再挨个目录 stat 文件，I/O 明显下降。
注意：-o / -a 之后新增了类文件不会自动被发现，必须再 dump 一次。CI 里部署脚本要带上这一步，否则「本地能跑，线上 Class not found」。
第二步：写对版本约束
常用约束按推荐程度排：
| 写法 | 含义 |
|---|
^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.0 <2.0 | 显式区间，适合跨大版本兼容的库 |
dev-main / 1.0.x-dev | 分支约束，配合 @dev 稳定性标记 |
安装时直接指定：
composer require monolog/monolog:^3.0
composer require phpunit/phpunit:^10.0 --dev
依赖装不上时不要靠猜，用这两条命令看到底是谁挡住了：
composer why-not monolog/monolog 3.0
composer show -t # 打印依赖树
composer outdated --direct
如果某个包只有 beta 版，可以在包名后加稳定性后缀 :^2.0@beta，或者在根部统一放宽：
{ "minimum-stability": "stable", "prefer-stable": true }
注意：^0.3.1 的实际含义是 >=0.3.1 <0.4.0，因为 0.x 被视为不稳定版本，别以为它会升到 0.9。另外 composer.lock 必须提交进仓库，它是团队和线上环境版本一致的唯一保证。
顺带一个高频坑：本地 PHP 版本和线上不一致时，可以锁死平台版本，避免解析出线上跑不了的依赖：
composer config platform.php 8.1.0
第三步：接入私有包
私有包本质还是 Composer 包，区别只是「从哪里拿」。在 composer.json 加 repositories：
1）Git 仓库（VCS 方式）
{
"repositories": [
{ "type": "vcs", "url": "git@gitlab.company.com:lib/payment-sdk.git" }
],
"require": { "company/payment-sdk": "^1.4" }
}
2）本地路径（开发调试最省事）
{ "repositories": [ { "type": "path", "url": "../payment-sdk", "options": { "symlink": true } } ] }
软链方式下改完私有包代码立刻生效，不用 composer update。
3）私有 Packagist（Satis / Private Packagist / Repman 自建）
{ "repositories": [ { "type": "composer", "url": "https://packagist.company.com" } ] }
认证写在项目根的 auth.json，或用环境变量：
{
"http-basic": { "packagist.company.com": { "username": "deploy", "password": "TOKEN" } },
"github-oauth": { "github.com": "ghp_xxx" }
}
也可以整体塞进环境变量：
export COMPOSER_AUTH='{"http-basic":{"packagist.company.com":{"username":"deploy","password":"TOKEN"}}}'
注意：auth.json 绝不能提交到仓库（把它加进 .gitignore）。CI 里用环境变量注入。用 SSH 方式拉包时，部署机需要配好 deploy key 和 known_hosts，否则会卡在交互式确认上。
第四步：上线前的检查清单
composer validate --strict # 校验 composer.json 语法与规范
composer diagnose # 检查网络、代理、镜像配置
composer install --no-dev -o -a --no-scripts # 生产安装
composer audit # 已知漏洞扫描
国内网络慢可以换镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。依赖解析爆内存时加 COMPOSER_MEMORY_LIMIT=-1。
注意：生产环境用 composer install（读 lock），不要用 composer update，后者会顺带升级依赖，等于在线上做一次未经测试的变更。
另外提醒一句：并不是所有 PHP 系统都需要 Composer。像 Clara BBS 这类无框架轻量级论坛系统，明确不需要 Composer、不需要命令行，上传文件后访问 install 走安装向导即可，插件靠运行时钩子加载、保存即生效。本文的内容适用于你自己写的项目，或者引入了 Composer 依赖二次开发的场景。
小结
- 自动加载三件套：新代码 PSR-4、老代码 classmap、函数库 files；改完必须
dump-autoload
- 线上加
-o -a 提升类查找性能，代价是新增类要重新 dump
- 版本约束默认用
^，装不上先 composer why-not 而不是瞎改约束
composer.lock 提交，线上只跑 composer install --no-dev- 私有包三选一：VCS 仓库、path 软链（开发）、自建 composer 仓库（规模化）
- 认证信息走
auth.json 或 COMPOSER_AUTH，永远不进 Git
正式会员
认证极客
