Composer 2.5.0+已移除self-update命令，运行即报“Command not defined”，必须手动重装；旧版本则需排查权限（改composer文件归属）、网络（切官方源绕过镜像缓存）或PHP兼容性问题。
composer self-update 报错不是小毛病，而是权限、网络或版本机制三者之一出了问题。直接删重装能绕过，但不解决根源；多数人卡在“明明改了镜像却没用”或“提示 Permission denied 却不知道改哪个文件”。
检查 self-update 命令是否还存在
Composer 2.5.0+ 已彻底移除 self-update 命令，运行就报 Command "self-update" is not defined。别浪费时间查网络或权限——它就是没了。
- 运行
composer --version：- 输出含
2.5.0或更高 → 必须重装，self-update不再可用 - 输出是
2.4.x或1.x→ 命令仍有效，可继续排查
- 输出含
- 同时运行
which composer和ls -l $(which composer)：- 若路径是
/usr/bin/composer（apt/brew 安装），别用self-update，该走包管理器：sudo apt install --only-upgrade composer或brew upgrade composer - 若是
/usr/local/bin/composer且属主为root，后续所有操作都会继承权限混乱
- 若路径是
Permission denied 错误到底该修哪个文件
self-update 报 Permission denied，说明当前用户无权写入 Composer 的可执行文件本身，不是 vendor 或缓存。
- 先确认安装路径：
which composer - 检查归属：
ls -l $(which composer)- 若属主不是你（比如显示
root root），运行：sudo chown $USER:$(id -gn) $(which composer) - 别动整个
/usr/local/bin/目录权限，只改这一个文件
- 若属主不是你（比如显示
- Windows 用户注意：PowerShell 或 CMD 若以“管理员身份运行”执行过
self-update，会导致生成的composer.phar被设为只读，右键属性里取消“只读”即可
国内用户“Up to date”但版本很旧，其实是镜像在骗你
阿里云、腾讯云等镜像会代理 https://getcomposer.org/ 的 Releases API，但 self-update **完全不读镜像配置**——它只连这个地址。镜像缓存了“已是最新”的响应，导致你永远升不到新版。
- 临时切回官方源（仅对 self-update 生效）：
composer config -g repo.packagist composer @#@#@#@#@#@#@#@#@#@0 - 再运行：
composer self-update - 升级成功后立刻换回镜像：
composer config -g repo.packagist composer @#@#@#@#@#@#@#@#@#@1 - 注意：
composer clear-cache对self-update无效，它不走缓存
手动更新是最稳的兜底方案
当网络拦截 getcomposer.org、PHP 版本不匹配（如 PHP 7.4 无法运行 Composer 2.6+）、或权限修复后仍失败，手动替换最可靠。
- 下载最新版：
php -r "copy('@#@#@#@#@#@#@#@#@#@2', 'composer-setup.php');" - 验证签名（可选但推荐）：
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1ccd8432c1c946f68b08260cf1262fd00d91a36303d7a7477d0c21f8927b7')... - 安装到用户可写路径：
php composer-setup.php --install-dir=$HOME/bin --filename=composer - 确保
$HOME/bin在$PATH中，并优先于系统路径
真正容易被忽略的是：错误信息里写的“Permission denied”路径，往往不是你第一反应去修的那个目录——它可能是 ~/.composer/cache 下某个临时锁文件，也可能是 /tmp 里 Composer 解压用的 staging 目录。遇到反复失败，用 strace -e trace=mkdir,open,write,chmod composer self-update 2>&1 | grep -i denied 才能定位真实失败点。
