Composer自v2.5.0起已彻底移除self-update命令，执行会报“Command not defined”，必须通过官方安装脚本重装并校验SHA-384与GPG签名，同时确认PHP≥8.0、路径权限及镜像配置。
Composer 的 self-update 命令从 v2.5.0 起已被官方彻底移除，不是你配错了，也不是网络问题——它根本不存在了。 所有仍试图运行 composer self-update 并报错 Command "self-update" is not defined 的情况，都是因为环境里还残留旧文档或旧脚本。现在升级 Composer，只有一条路：手动重装 composer.phar，且必须带校验、走对路径、避开权限陷阱。
为什么 self-update 总是报错或静默失败
这不是命令写错了，而是三件事同时失效了：
- PHP CLI 缺
openssl扩展 → 连不上https://getcomposer.org/（运行php -m | grep openssl看有无输出） - 当前用户对
/usr/local/bin/composer没写权限 →Permission denied不是 bug，是 Unix 权限机制在起作用 - 你配了阿里云镜像源，但
self-update根本不走那个配置 → 它只认https://getcomposer.org/，镜像缓存会直接返回 “Up to date”，让你误以为已是最新版
Linux/macOS 下手动替换 composer.phar 的安全路径
别碰 /usr/local/bin/composer，除非你确定用 sudo 管理全局二进制且能承担后续权限混乱风险。更稳的做法是把新 composer.phar 放进用户可写目录：
- 先查当前生效路径：
which composer - 如果返回
/usr/local/bin/composer且ls -l $(which composer)显示属主是root，就别硬覆盖 - 改用用户级安装：
curl -sS https://getcomposer.org/installer | php -- --install-dir=$HOME/bin --filename=composer - 确保
$HOME/bin在$PATH前置位置（检查echo $PATH，必要时追加export PATH="$HOME/bin:$PATH"到~/.zshrc或~/.bashrc） - 验证：
which composer应返回/home/yourname/bin/composer，且ls -l显示属主是你自己
Windows 用户手动下载替换的坑点
浏览器“另存为”下载的 composer.phar 很可能被自动加了 .zip 后缀，或者被 Windows Defender 拦截导致替换后执行报 Access is denied：
- 别用浏览器下载，用
curl -o composer.phar https://github.com/composer/composer/releases/download/2.9.6/composer.phar（替换成最新 release tag） - 下载后先校验 SHA256（GitHub Release 页面下方有 hash 值）：
certutil -hashfile composer.phar SHA256（Windows） - 覆盖前确认目标路径：运行
where composer或composer --version --no-ansi查加载位置 - 如果原文件在
C:\ProgramData\ComposerSetup\bin\，需以管理员权限运行 CMD 替换；但更推荐改用用户目录（如%USERPROFILE%\bin\）并调整PATH - 替换后运行
php -d phar.readonly=0 composer.phar --version验证是否可执行（若报PharError，需在php.ini中设phar.readonly = Off）
CI/CD 和 Docker 中必须绕过的雷区
在 GitHub Actions、GitLab CI 或 Docker 构建中，composer self-update 是死路一条——它要么因无交互卡住，要么因只读文件系统失败，要么被镜像缓存误导：
- CI 中务必显式指定版本：
curl -sS https://getcomposer.org/installer | php -- --version=2.9.6 --install-dir=/tmp --filename=composer，再export PATH="/tmp:$PATH" - Dockerfile 里别写
RUN composer self-update，改用多阶段 COPY 或apk add php-composer（Alpine） - 容器内文件系统只读？那就提前把
composer.pharCOPY 进镜像，而不是运行时下载 - 所有手动安装都必须带 SHA-384 或 GPG 校验（官网 release 页面提供），否则 CI 可能被中间劫持污染
真正麻烦的从来不是下载和替换动作本身，而是 composer.phar 所在路径的权限归属、PHP CLI 的 openssl 和 phar.readonly 配置、以及国内镜像对更新协议的代理策略——这三样漏掉任何一样，手动更新就会变成一个安静的失败。
