确认是否在用 Composer 1.x：运行 composer --version，若显示 Composer version 1.x.x 即为已停更旧版；注意部分系统中 which composer 与实际路径可能不一致，建议用 ls -l $(which composer) 查看真实指向。
怎么确认自己还在用 Composer 1.x
直接运行 composer --version，如果输出是 Composer version 1.10.22 或类似带 1. 开头的，就坐实了——你正用已停止维护的旧版。注意：有些系统（比如 macOS 用 Homebrew 装的老版本）或 Docker 镜像里预装的 composer 是硬链接到 /usr/local/bin/composer.phar 的，which composer 和 composer --version 结果可能不一致；建议顺手跑一句 ls -l $(which composer) 看它到底指向哪。
为什么不能用 composer self-update 升级到 2.x
因为 Composer 官方明确禁用了跨主版本的自更新：self-update 在 1.x 上最多升到 1.10.22，永远触不到 2.x。这不是 bug，是设计——v1 和 v2 的依赖解析引擎、插件 API、平台检查逻辑全都不兼容，强行热更会崩。
- 执行
composer self-update --2在 v1 环境下会报错或静默失败（不是所有安装方式都支持该参数） - 如果你看到提示
Upgrading to version 2.x，大概率是误用了第三方镜像或被篡改的二进制 - 真正可靠的方式只有一种：下载官方
composer.phar覆盖
一键覆盖升级的实操命令（带校验）
下面这组命令是目前最稳妥的升级路径，含 SHA384 校验，防下载劫持：
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');"
若提示 Permission denied，说明你没权限写 /usr/local/bin，改用用户级安装：
- 把
--install-dir=/usr/local/bin换成--install-dir=$HOME/bin - 确保
$HOME/bin在$PATH中（检查echo $PATH，必要时加到~/.bashrc或~/.zshrc）
升级后第一次运行就报错？先看是不是插件惹的祸
Composer 2.x 默认启用 plugin-api-version=2.0，而很多老插件（比如早已废弃的 hirak/prestissimo）根本不适配，会导致 composer install 卡在 Package operations: 0 installs, 0 updates, 0 removals 不动。
- 检查项目根目录的
composer.json，删掉"config": { "plugins": [...] }或全局配置里的对应项 - 运行
composer global config --unset plugin-api-version（如有） - 再试一次
composer install，如果还卡，加-v参数看具体停在哪一步
别急着回滚——v2 的依赖解析器能给出比 v1 清晰得多的冲突提示，比如明确告诉你 “A 2.0 要求 B ^3.0，但 C 4.0 锁定了 B ^4.0”，这种信息在 v1 里往往藏在几百行堆栈里。
