必须升级Composer 1.x至2.x，因其已于2022年12月停止维护，导致PHP 8.1+包安装失败；需用官方脚本重装，禁用self-update，验证三要素并同步更新CI环境。
确认当前版本和升级必要性
如果你的 composer --version 输出是 1.x（比如 1.10.22），那必须升级——Composer 1.x 已于 2022 年 12 月彻底停止维护，现在连很多 PHP 8.1+ 的包都装不上，不是报错就是静默失败。
常见误判点：which composer 和 composer --version 结果不一致。比如 macOS 上用 Homebrew 安装的老版本，which composer 指向 /opt/homebrew/bin/composer，但实际执行的是硬链接到某个旧 composer.phar；Linux 上可能被软链到 /usr/local/bin/composer.phar，而你看到的版本其实是那个文件的内容。
- 先运行
which composer确认路径 - 再运行
ls -l $(which composer)看是不是符号链接 - 如果是链接，
readlink -f $(which composer)才能看到真实文件位置 - 若路径在系统保护目录（如
/usr/bin）且无写权限，别硬 sudo 覆盖，改用用户级安装
用官方脚本覆盖安装（唯一推荐方式）
composer self-update 命令已在 Composer 2.5.0 中被彻底移除，执行会直接报错 Command "self-update" is not defined。这不是你环境的问题，是官方主动废弃了增量更新机制——所有升级都必须走重装流程，靠脚本内置的 SHA-384 校验和 GPG 验证来保安全。
最稳妥的一键命令（请复制整行执行）：
curl -sS https://getcomposer.org/installer | php -- --filename=composer --install-dir=/usr/local/bin/
注意三点：
-
--install-dir必须和which composer输出的路径一致；不确定就先改成$HOME/bin，再确保该目录在$PATH里（如export PATH="$HOME/bin:$PATH"） - 别手动下载
composer.phar然后sudo mv替换——绕过校验等于开后门 - 执行完立刻运行
hash -r（bash/zsh）或重启终端，否则 shell 还缓存着旧路径，composer --version仍显示 1.x
升级后首次运行常见的“假卡死”现象
执行 composer install 或 composer update 后，控制台只输出 Package operations: 0 installs, 0 updates, 0 removals 就停住不动——这不是卡死，是 Composer 2 默认启用了 plugin API v2，而一些老插件（比如已废弃的 hirak/prestissimo）根本不兼容，直接被跳过，导致后续逻辑没触发。
检查方法：
- 运行
composer config --list | grep plugins，看是否启用了过时插件 - 搜项目根目录和全局配置（
~/.composer/config.json或$XDG_CONFIG_HOME/composer/config.json）里的"plugins"字段 - 删掉相关配置，或加
--no-plugins临时绕过验证
另一个常见干扰：某些 CI 环境中 composer.phar 是只读挂载，脚本执行成功但文件没真正写入，得换用 --install-dir 到可写路径并显式加入 PATH。
验证是否真升级成功 & 后续动作
别只信 composer --version，要验证三件事：
- 执行
composer check-platform-reqs，它在 Composer 2 中是强制平台检查功能，如果 PHP 版本低于 7.2.5 会直接报错退出——这是 v2 的硬性门槛 - 跑一次
composer outdated，v2 的输出格式更清晰，带颜色标识，且能正确识别私有仓库包 - 在项目里执行
composer update --dry-run，观察依赖解析速度和内存占用：v2 解析复杂项目通常快 30%~50%，内存峰值下降一半以上
最容易被忽略的是 CI/CD 流水线里的镜像或基础容器——很多团队本地升级了，但 Jenkins/GitLab Runner 用的还是预装 Composer 1.x 的 Docker 镜像，部署时依然失败。得同步更新构建环境中的 Composer 版本，不能只改本地。
