最常见原因是镜像源缓存误导——配置了阿里云等国内镜像后，self-update误将镜像响应当官方版本，未连https://getcomposer.org/校验；需先切官方源（composer config -g repo.packagist composer https://packagist.org）、再self-update、最后换回镜像，并用composer --version验证；升v3必须显式执行composer self-update --3（仅支持≥2.5+），否则默认只更新同主版本内小版本。
composer self-update 为什么提示“Up to date”却还是旧版本
最常见原因是镜像源缓存误导 —— 你配置了阿里云、腾讯云等国内镜像（https://mirrors.aliyun.com/composer/），但 self-update 会把镜像当“官方”，直接读缓存响应，根本没连 https://getcomposer.org/ 校验真实版本。
临时切回官方源再更新：
composer config -g repo.packagist composer https://packagist.orgcomposer self-update- 成功后立刻换回镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
别只信终端输出的 “Updated”，一定要执行 composer --version 看实际数字，尤其注意 Windows 可能因 PATH 缓存显示旧版本。
升级到 v3 必须加 --3，否则永远卡在 v2
v2 和 v3 是不兼容主版本，self-update 默认策略就是拦住跃迁。即使 v3.0.2 已发布（截至 2026 年 5 月已稳定），运行 composer self-update 仍只会升到 v2.x 最新版（如 2.7.7）。
必须显式指定通道或版本：
- 升到最新 v3：
composer self-update --3（注意是两个短横线 + 数字 3） - 退回 v2 最新版：
composer self-update --2 - 指定精确版本：
composer self-update 3.0.2
⚠️ --3 参数仅在 Composer ≥ 2.5+ 中支持。若当前是 2.4.x，得先 composer self-update 升到 2.5+，再执行 --3。
Permission denied 或 Signature mismatch 怎么办
Windows 常见：系统锁定正在运行的 composer.phar，导致写入失败，报错类似 file_put_contents(): failed to open stream 或 Access is denied。
绕过方法是用 PHP 显式调用 PHAR 文件本身：
- 先查路径：
where composer（Windows）或which composer（macOS/Linux） - 再执行：
php "C:\ProgramData\ComposerSetup\bin\composer.phar" self-update - 如果
php不在 PATH，用绝对路径：C:\php\php.exe "C:\path\to\composer.phar" self-update
Linux/macOS 权限问题多因安装在 /usr/local/bin 等系统路径，sudo composer self-update 能临时解决，但长期建议重装到用户目录（如 $HOME/bin），避免每次都要 sudo。
升级后 lock 文件和插件行为可能突变
v3 移除了 composer.lock 中的 content-hash 字段，改用更严格的锁文件校验逻辑。老项目首次用 v3 执行 composer install，可能报错：
The lock file does not contain require-dev information
这不是 bug，是格式变更。解决方案是删掉现有 composer.lock，再跑一次 composer install 重建。
另外，v3 对插件兼容性要求更高。如果你项目用了自定义 installer 或老旧第三方插件（比如某些私有仓库适配器），升级前务必在测试分支验证，而不是直接在 CI 或生产环境跑 self-update --3。
