必须手动安装官方 Composer PHAR 并校验 SHA384：系统源版版本陈旧、不兼容新版 PHP 和依赖约束，且 /usr/share/php/composer 不可写；需补全 php-zip/php-phar 等扩展并确保 /usr/local/bin 在 PATH 中。
Ubuntu 上别用 apt install composer
系统源里的 composer 是“假全局”：版本卡在 2.0–2.2（2026 年已落后 5 个大版本），不支持 ^2.5 这类依赖约束，PHP 8.3 兼容性差，升级会失败——因为它的二进制实际指向 /usr/share/php/composer/composer，该路径不可写。你运行 composer --version 看着正常，但一执行 composer install 就报错，就说明中招了。
必须手动安装官方 PHAR 并校验 SHA384
这是唯一能确保安全、可用、可升级的方式。漏掉校验步骤，PHAR 文件可能被中间人篡改，后续所有依赖安装都不可信。
- 先装齐 PHP 运行依赖：
sudo apt update && sudo apt install -y php-cli php-zip php-json php-phar php-xml unzip git - 下载并校验（命令可直接复制粘贴）：
EXPECTED_CHECKSUM="$(curl -sS https://composer.github.io/installer.sig)"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"
if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then echo 'Integrity check failed' >&2; rm composer-setup.php; exit 1; fi - 安装到系统级路径：
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer && rm composer-setup.php
PATH 和权限问题比想象中更常发生
即使 composer 文件已放在 /usr/local/bin，你也可能遇到：bash: composer: command not found 或 Permission denied。这不是 Composer 的问题，而是 shell 没找到它，或文件没执行权。
- 检查 PATH 是否含
/usr/local/bin：echo $PATH | grep -q '/usr/local/bin' || echo "警告：/usr/local/bin 不在 PATH 中" - 补 PATH（zsh 用户改
~/.zshrc，bash 用户改~/.bashrc）：echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc - 补执行权限（极容易被忽略）：
sudo chmod +x /usr/local/bin/composer
php-zip 和 php-phar 缺失不会在 --version 报错，但会让 install 直接崩溃
你看到 composer --version 成功输出，就以为万事大吉？错。一旦运行 composer install，就会卡住或抛出 Class 'ZipArchive' not found、PharData not found 这类错误——它们是 Composer 解压依赖包的底层支撑，但 Ubuntu 默认不装全。
- 验证是否启用：
php -m | grep -E 'zip|phar|json'（必须全部出现） - 若缺失，重装对应模块：
sudo apt install -y php-zip php-phar php-json - 注意：CentOS/RHEL 用户还需先启用 PHP 模块流，如
sudo dnf module enable php:remi-8.2
php-zip 和校验步骤。前者让整个安装流程“看似成功实则瘫痪”，后者让生产环境暴露在供应链攻击风险里——这两点没有容错余地。 
