Composer 2.x 升级失败主因是路径权限、锁文件不兼容、插件API断裂及命令弃用；需重装官方脚本、删vendor与lock、更新插件声明、替换dump-autoload -o为--apcu等。
Composer 2.x 没有兼容模式，升级后报错不是配置问题，而是环境、插件或锁文件不匹配的明确信号。 它不会“自动降级行为”来迁就旧项目，所有报错都指向具体可查的断裂点。
composer self-update --2 为什么没反应或仍显示 1.x
这是最常被误判为“升级失败”的现象，本质是安装路径和权限问题：
- 运行
which composer查真实路径；若输出是/usr/bin/composer或/opt/homebrew/bin/composer，说明它来自系统包管理器（apt/brew），self-update默认无权覆盖只读路径 -
ls -l $(which composer)若显示符号链接指向/usr/share/composer/composer.phar等只读位置，self-update实际静默失败 - Homebrew 安装的 Composer 从 2.5.0 起已彻底移除
self-update命令，执行会直接报错Command "self-update" is not defined - 正确做法：跳过
self-update，用官方脚本重装——php -r"copy('https://getcomposer.org/installer', 'composer-setup.php');"→ 校验 SHA384 →sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
Your lock file does not contain a compatible set of packages
这不是警告，是 Composer 2.x 的硬性拒绝。v1 生成的 composer.lock 缺少 content-hash、平台哈希字段，且依赖解析逻辑已重写，无法复用。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 必须删除两个文件：
vendor/（整个目录，不能只删子目录）和composer.lock（保留composer.json） - 执行
composer install后，它会重新解析全部依赖并生成 v2 格式锁文件；首次耗时略长，但后续更稳定 - CI 流水线中若缓存了旧
composer.lock，需确保上传前由 Composer 2.x 生成，否则install直接退出 - 如果删完重装仍报错，检查
composer.json中是否有"config": { "platform": { "php": "7.1.0" } }这类低版本声明——它会覆盖真实 PHP 版本，导致解析器误判
Plugin X is not compatible with Composer 2
插件不兼容不是偶然，是 API 层面断裂。Composer 2 强制要求插件在 composer.json 的 require 字段中声明 "composer-plugin-api": "^2.0"（实际建议 ^2.2.0），否则加载时被跳过或报错。
- 运行
composer diagnose，末尾会列出不兼容插件名称；但注意它可能被缓存绕过，需配合composer install -v观察是否出现loading日志 - 典型已归档插件：
hirak/prestissimo（v2 下静默失效，表现为卡在Package operations: 0 installs, 0 updates）、fxp/composer-asset-plugin（完全不兼容，需迁移到 asset-packagist.org） - 别急着
composer remove——先查 Packagist 页面，看该插件最新版是否已支持 ^2.0；有些作者悄悄发布了兼容版但没更新 README - 临时绕过：加
--no-plugins参数运行命令，验证是否真由插件引发；但生产环境不能长期依赖此参数
升级后命令行为突变，比如 dump-autoload -o 失效
Composer 2.x 移除了 dump-autoload --optimize（即 -o），也不再默认启用 APCu 优化。这不是 bug，是设计取舍：自动优化被证明在多数场景下收益有限，且易与 OPCache 冲突。
-
composer dump-autoload -o执行会报错Unrecognized option: o；正确替代是composer dump-autoload --apcu（需启用 ext-apcu） - 若不需要 APCu，直接删掉
-o即可；新版 autoloader 本身已做性能优化，无需手动触发“优化” -
composer update默认启用--with-dependencies，行为比 v1 更激进；如需保守更新，显式加--no-update-with-dependencies -
composer create-project新增--remove-vcs，旧脚本若依赖git clean行为，需显式加上该参数，否则残留 .git 目录
真正麻烦的从来不是升级动作本身，而是那些藏在 composer.json 里多年没动过的 require-dev 条目、被遗忘的私有仓库配置、以及插件中调用的已废弃内部类——它们不会报错，但会让 composer install 在某个深夜突然卡住，且毫无日志提示。
