composer self-update 默认不升级到 v3 是设计行为，仅限当前主版本内更新；需加 --stable 才能升至最新稳定版（如 3.5.0），但可能引发插件兼容问题。
composer self-update 为什么没更新到最新稳定版
默认情况下 composer self-update 只升级到当前稳定通道的最新版本，不跨主版本（比如卡在 2.2.x 就不会自动升到 2.5.x），更不会跳到 v3 —— Composer 官方把 v3 当作独立发布线，需显式指定。
- 执行
composer self-update后版本停在2.2.22或类似旧版，不是 bug，是设计行为 - Composer 2.x 和 3.x 是并行维护的：2.x 仍接收安全修复，3.x 是新功能主线
- 如果项目依赖要求
^2.2或锁死了composer-plugin-api版本，强行升级到 v3 可能导致插件失效
想升到最新稳定版（含 v3）必须加 --stable 参数
--stable 不是指“稳定通道”，而是告诉 Composer：放开主版本限制，取所有已标记为 stable 的最高版（目前是 3.5.0）。
- 运行
composer self-update --stable才可能升到 v3.x - 不加参数时等价于
composer self-update --1（v1）或--2（v2），取决于你当前大版本 - 国内用户若遇到超时，可先设镜像：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（注意该镜像已停用，应换为https://mirrors.aliyun.com/composer/）
升级后 composer install 报错 “Plugin API version mismatch”
v3 默认使用新版插件协议 composer-plugin-api: ^3.0，而很多老插件（如 hirak/prestissimo、fxp/composer-asset-plugin）只支持 v1/v2，会直接拒绝加载。
- 检查报错里是否含
requires composer-plugin-api ^2.0或类似提示 - 临时降级回 v2：运行
composer self-update --2 - 长期方案是替换插件：例如用原生
composer install --prefer-dist代替 prestissimo；前端资源改用yarn或npm管理，而非 asset-plugin
CI/CD 脚本里写死 composer self-update 很危险
未锁定版本的自更新，在某次构建中突然从 v2 升到 v3，可能导致整个流程失败——尤其当 Docker 镜像缓存了旧版 Composer，又没做版本校验时。
- CI 中推荐固定版本：
composer self-update 2.5.8或composer self-update 3.5.0 - 用
composer --version做前置检查，和预期不符就 exit 1 - 不要依赖全局 Composer 版本做关键逻辑判断，比如用
composer show --outdated结果驱动部署，v2/v3 输出格式有差异
composer --version 和项目 composer.json 里 config.platform.composer 的声明——这个字段常被忽略，但它会强制 Composer 模拟某个版本行为，哪怕你本地已是 v3。 
