Debian 下解决 Composer 兼容性问题的实用方案
一 先厘清职责与环境
二 快速排查清单
php -v、php -m | grep -E 'pdo|mbstring|xml|curl|gd|intl'（确认 CLI 与所需扩展一致）。which php、composer config -g platform.php（若设置了平台版本，可能与实际 CLI 不一致）。composer show -v、查看 composer.json 的 require 与 config.platform.php。composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/）。三 常见场景与对应处理
| 场景 | 典型症状 | 处理要点 |
|---|---|---|
| PHP 版本不满足 | 安装/更新时报 “Your requirements could not be resolved” 或 “PHP version does not satisfy that requirement” | 1) php -v 确认版本；2) 多版本用 sudo update-alternatives --set php /usr/bin/php8.1 切换 CLI；3) 短期可在 composer.json 加入 "config": { "platform": { "php": "8.1" } } 绕过检查（仅限确认代码可在当前环境运行）；4) 长期用 apt 升级到所需版本，或用 Docker/多版本管理工具 保持一致。 |
| 缺少系统扩展 | 运行期报 Class 'PDO' not found、ext-mbstring 缺失等 |
用 apt 安装扩展（如 sudo apt install php-pdo php-mbstring php-xml php-curl php-gd php-intl），并确保 CLI 配置加载这些扩展（php -m 验证）。 |
| 多版本 PHP 导致解析/运行不一致 | php -v 与 Web SAPI（FPM）版本不同，或 Composer 解析与 CLI 不一致 |
统一 CLI 与 FPM 的 PHP 版本（如都指向 8.1），必要时用 update-alternatives 或在 FPM 池配置中指定 php_admin_value[extension]=...。 |
| 依赖版本冲突 | Your requirements could not be resolved 并列出两个包对同一依赖的版本冲突 |
1) composer why vendor/pkg / composer depends vendor/pkg 定位来源；2) 先尝试 composer update 或 composer install --with-all-dependencies；3) 调整 composer.json 的版本约束（如 ^1.2、~2.0.3、`^5.4 |
| Composer 自身或网络问题 | composer --version 失败、安装依赖超时 |
1) 重装/更新 Composer：composer self-update；2) 清除缓存：composer clear-cache；3) 配置镜像或代理；4) 若 apt 源版本过旧，可用官方安装脚本 `curl -sS https://getcomposer.org/installer |
四 推荐的稳妥做法