直接运行composer self-update通常不能升级到最新稳定版，因它默认仅限同主版本内小版本更新；显示“Up to date”却仍是旧版，最常见原因是镜像源缓存导致误判，需先切官方源再执行，且须确保PHP≥8.0、权限正常、无网络拦截。
直接运行 composer self-update 通常就能升级到最新稳定版，但“能跑”不等于“升对了”——它可能卡在旧主版本、被镜像缓存欺骗、或因 PHP 版本不兼容静默失败。
为什么 composer self-update 显示 “Up to date” 却仍是旧版？
最常见原因是配置了国内镜像源（如阿里云、腾讯云），它们会代理并缓存 https://getcomposer.org/ 的响应，导致 Composer 误判远程版本号，根本没连上官方服务器校验。
- 先临时切回官方源：
composer config -g repo.packagist composer https://packagist.org - 再执行：
composer self-update - 升级成功后可立即换回镜像（推荐阿里云）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 注意：
--mirror参数只影响下载阶段，不解决校验逻辑问题，不能替代切源操作
如何升级到 v3 或指定主版本？
composer self-update 默认只在当前主版本内更新小版本（如 2.5.8 → 2.5.12），不会跨主版本。v3 是不兼容 v2 的重大变更，必须显式指定通道。
- 确认当前版本至少为
2.5+（否则不识别--3）：composer --version - 升级到 v3 最新版：
composer self-update --3 - 降级回 v2 最新版：
composer self-update --2 - 查看所有可用通道和版本：
composer self-update --list - v3 移除了
composer.lock中的content-hash，首次用 v3 运行install可能报错The lock file does not contain required hash，需先composer update --lock重生成
权限错误、PHP 版本不兼容、签名失败怎么处理？
这三类问题常导致 self-update 静默失败或命令失效，错误信息却很模糊。
-
Permission denied或Could not write to /usr/local/bin/composer：别急着加sudo；优先重装到用户目录：php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php --filename=composer --install-dir=$HOME/bin，再确保$HOME/bin在$PATH前置 - PHP 版本太低（如仍在用 PHP 7.4）：Composer 2.5+ 要求 PHP ≥ 8.0，强行升级后任何命令都会因
Attribute语法报Fatal error；应先升级 PHP，或临时降级 Composer：composer self-update 2.4.4 -
Signature mismatch：可能是网络截断或证书问题；加-vvv查日志，或临时跳过验证（仅调试）：composer self-update --no-sig-check；生产环境务必禁用该参数
CI/CD 流水线里自动升级要注意什么？
无交互环境（如 GitHub Actions、GitLab CI）中，composer self-update 默认会卡在确认提示，导致构建超时失败。
- 必须加
--no-interaction：composer self-update --no-interaction - 如果使用基础镜像（如
php:8.2-cli），其自带的 Composer 往往陈旧，CI 脚本第一句就该做升级，否则可能因插件签名验证失败导致composer install报错 - CI 中不建议用
--snapshot或--preview；固定版本更可控，例如：composer self-update 2.7.7 - 升级后务必跟一句
composer --version，避免缓存导致后续命令仍调用旧二进制
真正容易被忽略的是：升级不是单点动作，它隐式依赖 PHP 版本、文件权限、镜像源策略三者同时就绪。漏掉任一环，self-update 就会变成一个没有报错、也没有生效的“假成功”。
