Composer 1.x 已于2022年12月停止维护，新项目必须使用v2.x；若composer --version显示1.x版本（如1.10.22），需手动下载官方composer.phar覆盖升级，因self-update无法跨主版本升级。
Composer 1.x 已于 2022 年 12 月停止维护，所有新项目必须使用 composer v2.x；如果你还在用 composer --version 显示 1.10.22 或类似版本，说明你没升级，且可能已无法安装某些新版 PHP 包（比如依赖 php >=8.1 的包会因 Composer 1 的解析器限制直接失败）。
检查当前版本并确认是否需要升级
运行以下命令查看真实版本：
composer --version
如果输出包含 2.（如 Composer version 2.5.8），跳过后续步骤；否则需升级。注意：有些系统（如 macOS Homebrew 安装的旧版）或 Docker 镜像里预装的 composer 可能是 1.x 且被硬链接到 /usr/local/bin/composer，which composer 和 composer --version 结果不一致的情况很常见。
- 用
which composer确认二进制路径 - 用
ls -l $(which composer)看是否为符号链接（常见指向/usr/local/bin/composer.phar） - 若路径是
.phar文件，直接替换即可；若是包管理器（如 apt / brew）安装的，优先用对应包管理器升级
一键升级命令（推荐全局覆盖方式）
最稳妥、兼容性最好的升级方式是直接下载官方 composer.phar 并覆盖本地文件：
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6dc97f') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"
执行后运行 composer --version 应显示 2.x。注意：--install-dir 必须有写权限，若报 Permission denied，改用用户级安装（如 --install-dir=$HOME/bin）并确保该目录在 $PATH 中。
升级后常见报错与修复点
升级后首次运行 composer install 或 composer update 可能触发以下问题：
-
Package operations: 0 installs, 0 updates, 0 removals却卡住不动 → 是因为 v2 默认启用plugin-api-version=2.0，部分老旧插件（如hirak/prestissimo）已废弃且不兼容，需从composer.json的config.plugins或全局配置中移除 -
Class 'Composer\Script\Event' not found→ 脚本中用了 v1 的 API，v2 中该类已移至Composer\Plugin\Capability\ScriptExecutionCapability，但更常见的是自定义脚本仍用use Composer\Script\Event;，应删掉或改用事件钩子标准写法 -
Deprecation warning: Your package name ... does not follow PSR-4 autoloading standard→ v2 对autoload校验更严格，检查composer.json中autoload/autoload-dev的命名空间与路径映射是否匹配实际目录结构
为什么不能只靠 composer self-update
composer self-update 在 v1 下默认只升到最新 v1.x 版本（如 1.10.22），**不会跨主版本升级到 v2**。只有当你已经运行过 v2 的 composer 二进制时，self-update 才会保持在 v2 分支。这是 Composer 的显式设计，避免自动跨主版本导致项目构建中断。所以不要依赖它来完成 1→2 升级。
v2 的核心变化（如更快的依赖解析、原生 HTTPS 包下载、更严格的语义化版本约束处理）都建立在重构后的依赖图算法上，不是补丁能覆盖的。手动替换二进制是最直接、最可控的方式。
