composer 2.5.0起已彻底移除self-update命令，执行会报“command not defined”，必须通过重装升级；需先用which composer和ls -l确认安装路径与链接类型，再检查插件兼容性、项目约束及ci配置。
不能用 composer self-update 升级到 v2 —— 这个命令在 2.5.0 起已被彻底移除，执行只会报错 Command "self-update" is not defined。必须重装，且重装前得先摸清当前安装路径、插件状态和项目约束是否扛得住。
怎么确认你还在跑 Composer 1.x？别信 composer --version 一眼结果
shell 缓存、软链接、硬链接都可能导致版本显示失真：
- 运行
which composer，看输出是/usr/local/bin/composer、/opt/homebrew/bin/composer还是$HOME/.local/bin/composer - 再执行
ls -l $(which composer)：如果带->，说明是符号链接；用readlink -f $(which composer)才能定位真实文件 - 若真实路径落在
/usr/bin或/usr/lib/php这类系统保护目录，且你没写权限，就别硬sudo mv替换 —— 大概率失败还污染环境 - macOS Homebrew 用户尤其注意：
which composer指向/opt/homebrew/bin/composer，但实际执行的可能是硬链接到某个已废弃的composer.phar
哪些插件会静默拖垮 composer install？
Composer 2 默认启用 plugin API v2，v1 插件加载即被跳过，不报错、不提示，只卡在 Package operations: 0 installs, 0 updates...：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 运行
composer show --plugins查当前启用的插件列表 - 重点排查已明确废弃的插件：
hirak/prestissimo、fxp/composer-asset-plugin、composer/installers旧版（^1.x） - 检查插件的
composer.json中是否声明了"require": {"composer-plugin-api": "^2.0"}；没声明或写的是^1.0就不兼容 - 临时验证：注释掉
composer.json中require-dev下所有插件条目，再跑composer install -vvv，观察Loading plugin日志是否消失
composer.json 哪些写法在 v2 里会直接拒装？
v2 的 SAT 求解器不妥协、不降级、不跳过，只要约束冲突就终止，不是网络慢或权限问题：
- 含
"dev-master"、"@dev"、"dev-xxx as y.z"的 require 条目 —— v2 默认禁用不稳定包，需显式加"minimum-stability": "dev"或换稳定标签（如"^2.8"） - 包名过时：比如用了下划线命名的旧包（
monolog/monolog正确，monolog_monolog就会被拒） - 私有仓库配置为
"type": "vcs"或"type": "package"—— v2 对 VCS 源支持变弱，应改用"type": "composer"配合私有 Packagist - 运行
composer why-not vendor/package:version，它比 v1 的why更准，能直指哪个依赖锁死了求解路径
升级后 composer install 报 “Root package requires X which is not installable” 怎么办？
这不是锁文件损坏，是 v2 解析器拒绝构造出满足全部约束的可行解。v1 可能凑合选个次优版本，v2 直接退出：
- 删掉
composer.lock和vendor/目录 —— 别复用旧 lock 文件，v2 锁格式含"lock-version": 2，v1 读不了 - 临时放宽某条约束测试：把
"monolog/monolog": "^2.0"改成"^2.8"，验证通过后再逐步收紧 - 若项目用了
config.platform，确保值与实际部署 PHP 版本完全一致（如设"8.1.0"就不能只写"8.1"） - CI 环境中必须同步更新：GitHub Actions / GitLab CI 脚本里，
composer install前加判断：grep -q '"lock-version": 2' composer.lock，否则构建会硬性失败
最常被忽略的是：重装完必须立刻运行 hash -r（bash/zsh）或重启终端，否则 shell 还缓存着旧路径，composer --version 仍显示 1.x；还有就是团队协作中，有人本地升了 v2，但 CI 用的还是 v1，composer.lock 格式不互通，一跑就崩。
