composer self-update --stable 能升至所有稳定版最高版本（如3.5.0），因它解除主版本限制；不加参数则仅限当前主版本内小版本更新（如2.7.6→2.7.7），且v2与v3不兼容，需确认php≥8.0、镜像源有效及路径正确。
composer self-update --stable 能升到当前所有稳定版里的最高版本，包括 v3.x（截至 2026 年 5 月，最新稳定版是 3.5.0），但它不是“默认行为”，也不是“无脑最安全选择”——它会跨主版本，而 v2 和 v3 不兼容。
为什么加 --stable 才可能升到 v3
不加参数的 composer self-update 默认只在当前主版本内更新小版本（如 2.7.6 → 2.7.7），哪怕 v3 已发布半年，它也完全无视。加 --stable 是明确告诉 Composer：“放开主版本限制，取所有标记为 stable 的最高版”。
- v2 和 v3 是并行维护线，不是“v2 升级后变成 v3”，而是两个独立二进制，锁文件格式、插件协议、PHP 最低要求（v3 强制
php ≥ 8.0）全不同 - 如果你当前是
2.2.22，直接跑composer self-update --stable可能失败，因为--stable在2.4-版本中不识别该参数；得先composer self-update升到2.5+，再加--stable -
--stable不等于“推荐用于生产”——它只是通道名，v3 的稳定版对老项目可能是灾难，比如插件报requires composer-plugin-api ^3.0错误
执行前必须确认的三件事
很多人输完命令回车就以为完事了，结果 composer --version 还是旧版，或者后续 install 直接报错。真正生效的前提是：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 运行
which composer（Linux/macOS）或where composer（Windows），确保你更新的是 shell 当前调用的那个路径；如果输出是/opt/homebrew/bin/composer，那self-update更新的只是它背后引用的 PHAR，不是脚本本身 - 检查镜像源：
composer config -g repo.packagist，若返回已下线的源（如https://packagist.phpcomposer.com），self-update会卡住或误判；应先切回官方源：composer config -g repo.packagist composer https://packagist.org - 确认 PHP 版本：
php -v，v3 要求php ≥ 8.0，若仍是 7.4，升级后首次运行就会因Attribute语法直接Fatal error
升级后立刻要验证的点
终端显示 Updating to version 3.5.0 (stable channel) 不代表成功落地。v3 的改动是破坏性的，尤其对已有项目：
- 首次运行
composer install可能报错：The lock file does not contain required hash—— 因为 v3 移除了content-hash字段，需先composer update --lock重生成 - 插件加载失败很常见，例如
hirak/prestissimo或私有仓库 installer，错误里带composer-plugin-api ^2.0就说明它不支持 v3，临时解法是composer self-update --2 - 检查
composer --version输出末尾的 commit hash 和日期，别只信版本号；如果含snapshot或beta字样，说明误进了开发通道，立刻composer self-update --stable回退
最常被忽略的是：升级不是单次操作，而是环境适配过程。v3 的 lock 文件结构、依赖解析策略、甚至 autoloader 生成逻辑都变了，测试分支跑通 install 和 dump-autoload 之后，才敢合入主干。
