Composer1.x和2.x有什么区别？升级版本与镜像适配【科普】-composer-PHP中文网

composer 2.x 是重写而非升级，与1.x完全不兼容：lock文件结构重定义、classmap-authoritative默认启用、插件需显式授权、镜像协议更严格，混用会导致安装中断。

composer1.x和2.x有什么区别？升级版本与镜像适配【科普】

Composer 2.x 不是“升级版”，而是重写的全新工具——混用 1.x 和 2.x 会导致 composer install 直接失败、类找不到、插件被拒，不是警告，是中断。

composer.lock 文件完全不互通，不是格式微调，是结构重定义

Composer 2.x 生成的 composer.lock 包含 "plugin-api-version": "2.2.0" 字段、新 content-hash 算法、扩展插件元数据等，Composer 1.x 解析时会报 Invalid lock file. Expected key "plugin-api-version" 并终止安装。

团队协作中，有人用 1.x 运行 composer update 提交旧锁文件，其他人用 2.x 拉取就会立即报错
CI 流水线若未统一版本，composer install 会静默失败，错误信息极短（常被误判为网络或权限问题）
降级不是删 vendor 重装，必须用 Composer 1.x 执行 composer update --lock 重新生成锁文件再提交

classmap-authoritative 默认启用，动态类加载会静默失效

Composer 2.x 默认开启 classmap-authoritative，意味着 autoloader 只认 classmap 里明确登记的类，跳过 PSR-4 fallback 和运行时路径拼接。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

Laravel 的 EventServiceProvider 动态注册监听器可能失效
files 类型加载中写 __DIR__ . '/stubs/' . $name . '.php' 这种拼接逻辑，在 2.x 下根本不会被扫描到
开发调试可用 composer dump-autoload --no-authoritative 临时绕过（2.x 支持，1.x 忽略该 flag）
若需兼容 1.x，应在 composer.json 中显式设 "classmap-authoritative": false

插件默认禁用，`allow-plugins` 必须显式声明

Composer 2.x 默认关闭所有第三方插件（包括 laravel/installer、phpstan/extension-installer），而 1.x 默认全开——这就造成「本地能跑，CI 报 Plugin not allowed」。

必须在 composer.json 根层级添加 "allow-plugins" 字段，例如：

{"allow-plugins": {"laravel/installer": true, "phpstan/extension-installer": true}}

未声明的插件会被直接跳过，不报错也不执行，行为难以察觉
旧版插件（如 hirak/prestissimo）已彻底不兼容，v2 API 要求实现 PSR-14 事件机制

镜像适配不是“换地址”，而是协议与响应格式校验更严

国内常用镜像（如阿里云、腾讯云、华为云）虽已支持 Composer 2.x，但部分老旧私有镜像或自建 Satis 实例仍返回 v1 格式的 packages.json，导致 2.x 拒绝解析。

关键检查点：镜像返回的 packages.json 中 dist.type 必须为 "zip" 或 "tar"，不能是已废弃的 "pack"
若使用自定义 repositories，确保其 type 是 "composer"，v2 对 "vcs" 类型源支持显著减弱
镜像配置本身不变（如 https://mirrors.aliyun.com/composer/），但需确认后端服务已升级到支持 v2 协议的版本
升级后首次 composer install 若卡在 “Loading from cache” 或报 Package manifest could not be found，大概率是镜像未适配