Composer ≥2.5.0 时 self-update 命令已被官方彻底移除，报“Command not defined”即确认需重装；系统包管理器（apt/brew）、Docker 或宝塔预装版因路径只读也无法更新，唯一可靠方式是卸载后用官方脚本覆盖安装到用户可写目录。
直接运行 composer self-update 被拒绝，大概率不是网络或权限位问题，而是你正用着一个“不能被更新”的 Composer 安装方式——它要么是系统包管理器装的（apt/brew）、Docker 预装的、宝塔面板托管的，要么已经升级到 v2.5.0+（该命令已被官方移除）。
执行 self-update 报 “Command not defined”
这是最明确的信号：你当前的 Composer 版本 ≥ 2.5.0，self-update 命令已从代码中彻底删除。别再试 --2 或加参数，它不会复活。
- 运行
composer --version确认输出是否含v2.5.0或更高（例如v2.7.7） - 运行
which composer和ls -l $(which composer)，看它是不是指向/usr/bin/composer或硬链接到只读路径 - 若确认是 v2.5+，唯一合法做法是重装：下载官方 phar 并覆盖，或用
curl -sS https://getcomposer.org/installer | php生成新composer.phar
执行 self-update 静默失败或卡在 “Up to date”
常见于国内镜像源缓存了旧响应，或 PHP 禁用了关键函数（如宝塔环境下的 putenv、proc_open）。
- 先切回官方源：
composer config -g repo.packagist composer https://packagist.org - 绕过禁用函数（宝塔等场景）：
/www/server/php/82/bin/php -d "disable_functions=" /usr/local/bin/composer self-update - 升级后立刻换回镜像源：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
执行 self-update 提示 Permission denied
错误路径通常指向 /usr/bin/composer 或 /opt/homebrew/bin/composer —— 这些位置默认不可写，self-update 尝试覆盖二进制文件时被系统拦截。
- 不要用
sudo composer self-update，这会让新文件属主变成 root，后续所有命令都得加 sudo - 正确做法是卸载旧版：
sudo apt remove composer（Ubuntu）或brew uninstall composer（macOS） - 然后用官方脚本安装到你有写权限的位置，例如：
php composer-setup.php --install-dir=$HOME/bin --filename=composer
self-update --2 为什么总不生效
这个参数只对「手动下载、可写、非系统路径」的 composer.phar 有效。apt/brew/Docker 镜像里的 Composer 都是硬链接或只读二进制，--2 不会触发重装，只会静默跳过或报错。
- 运行
readlink -f $(which composer)查真实路径；如果返回的是/usr/lib/php/composer.phar或类似只读路径，--2必然无效 - 别依赖 “升级”，要接受“替换”：删旧 + 下新 + 放到
$HOME/bin或~/local/bin这类你完全控制的目录 - 完成后运行
export PATH="$HOME/bin:$PATH"（并写入~/.bashrc），确保终端调用的是新版
最容易被忽略的是：Composer 的 CLI 版本和 Web 服务器（如 Nginx + PHP-FPM）用的 PHP 版本、扩展、禁用函数，完全是两套环境。你在终端能跑通 self-update，不代表项目里 composer install 就不会因 ext-zip 缺失或 disable_functions 拦截而失败——务必分开验证。
