Composer 2.x升级指南与注意事项

直接升级Composer 2.x安全且推荐，但必须确认PHP≥7.2.5、插件兼容性及删除composer.lock后重装——漏任一项均可能导致install失败或依赖错误。

直接升级到 Composer 2.x，这事儿本身是安全且推荐的。但别急着敲命令，有三件事必须提前确认：PHP版本够不够、插件是否兼容、以及composer.lock文件要不要处理。这三项里漏掉任何一项，composer install都可能失败，或者给你装上一堆错误的依赖包。

检查 PHP 版本和 Composer 安装方式是否允许升级

首先得明白，Composer 2.x 已经彻底抛弃了对 PHP 7.1 及以下版本的支持，并且硬性依赖 ext-zip 和 ext-json 这两个扩展。升级前，不妨先运行下面几个命令快速做个“体检”：

• php -v —— 输出结果必须是 7.2.5 或更高。如果显示的是 7.1.33 甚至 5.6.40，那么抱歉，你得先升级 PHP 本身。
• php -m | grep -E 'zip|json' —— 这个命令用来确认两个扩展都已加载，缺一不可。
• which composer 加上 ls -l $(which composer) —— 这组命令是检查 Composer 的安装方式。如果它指向系统级路径（比如 /usr/bin/composer）并且是个符号链接，那么直接用 self-update 升级很可能失败。这时候，更稳妥的做法是使用官方的安装脚本进行覆盖安装。

这里有个特别需要注意的变更：从 Composer 2.5.0 开始，composer self-update 这个命令被彻底移除了。如果你执行它看到报错 Command "self-update" is not defined，别怀疑是权限问题，这就是设计上的改变。

删 composer.lock 和 vendor/ 后再 composer install

为什么一定要删除旧文件？因为 Composer 2.x 的锁文件格式已经变了：它新增了 content-hash 字段，支持多平台哈希校验，而且解析器不再容忍 v1 时代那些模糊的版本约束。如果强行复用旧的 composer.lock，大概率会看到这样的错误：

Your lock file does not contain a compatible set of packages

所以，标准的操作流程应该是：

• 必须删除整个 vendor/ 目录（只删部分子目录可能会残留冲突）。
• 必须删除 composer.lock 文件（只保留 composer.json 就行）。
• 然后执行 composer install，让它基于新的规则完整重建依赖图。这个过程第一次可能会比 v1 耗时稍长，但后续的安装和更新速度会有明显提升。
• 如果你的 CI 流水线中使用了 composer install --no-dev，要留意一个细节：v2 版本在找不到 lock 文件时，会强制解析全部的 require-dev 依赖，这可能会暴露出一些之前被隐藏的版本冲突。

识别并处理不兼容插件与废弃命令

Composer 2 默认启用了插件沙箱机制，并且要求插件必须声明兼容 "composer-plugin-api": "^2.0"。市面上一些流行的 v1 时代插件已经失效了，比如：

• hirak/prestissimo（这个并行安装插件已经废弃，在 v2 下会被静默跳过，可能导致终端一直显示“卡在 Package operations: 0 installs…”的假象）。
• fxp/composer-asset-plugin（不再兼容，通常需要迁移到 npm 配合 asset-packagist.org 的方案）。
• 任何直接调用了 Composer\Package\Version\VersionParser 等 v1 内部类的私有安装器（installer）。

除了插件，一些命令的行为也发生了变化或被移除：

• composer dump-autoload -o —— 如果需要 APCu 加速，应改为 composer dump-autoload --apcu；如果不需要，直接去掉 -o 参数即可，因为新版本默认已经做了优化。
• composer update --no-dev 命令虽然还能用，但它会跳过所有 require-dev 中的包及其传递依赖。在 CI 环境中，如果你的测试依赖于 phpunit/phpunit 这类开发包，这个命令可能会误删它们。
• composer create-project 新增了 --remove-vcs 参数。如果你的旧脚本依赖 git clean 的行为，现在需要显式加上这个参数。

CI/CD 和私有包场景下的典型陷阱

在 GitHub Actions 或 GitLab CI 这类自动化流水线里，最容易踩坑的地方往往集中在锁文件的来源和插件上下文上：

• 务必确保流水线中使用的 composer.lock 是由 Composer 2.x 生成的。因为 1.x 生成的 lock 文件缺少关键的 content-hash 字段，v2 版本会直接拒绝读取。
• 在无 TTY 的非交互式环境中运行 composer install --no-interaction 时，最好加上 --no-suggest 参数。否则，v2 版本会尝试获取“建议安装”的包列表，可能导致请求超时。
• 对于私有的包，如果其 composer.json 里缺失了 type 字段或 autoload 配置，v2 可能会报错 Package manifest could not be found。解决方法很简单，补上一个最简配置即可：

{
  "name": "vendor/name",
  "type": "library",
  "autoload": {
    "psr-4": {"": "src/"}
  }
}

话说回来，真正难调试的问题，往往不发生在主流程里。那些被忽略的钩子脚本（比如 post-install-cmd）、自定义的安装器、或者 CI 中硬编码的旧版 composer.phar 路径——它们可能还在偷偷调用 v1 的事件顺序或内部类。这类错误不会立刻抛出，而是表现为诡异的自动加载失败或“class not found”，排查起来相当费神。所以，升级后的全面测试，必不可少。