Composer requires php错误 解决PHP版本不匹配问题【解决】

Composer报requires php>=X.X错误，本质是php CLI版本低于项目要求；需执行php -v确认实际版本，再通过Homebrew、update-alternatives或PATH调整使php命令指向正确版本。

composer 安装或更新时提示 requires php >= X.X 错误，本质是当前 PHP CLI 版本低于项目或包声明的最低要求。不是 Composer 本身坏了，而是它在严格执行依赖约束。

确认当前 PHP CLI 版本是否真不匹配

很多人改了系统 PATH 或重装了 PHP，却没意识到终端里运行的 php 命令可能还是旧版本。直接执行：

php -v

注意看输出的第一行（不是 Loaded Configuration File 对应的 ini 路径里的版本）。如果显示 PHP 7.4.33，但项目 composer.json 写着 "php": "^8.1"，那就必然报错。

• Mac 用户常见于 Homebrew 安装多个 PHP 版本后未用 brew link --force php@8.2 切换默认
• linux 用户容易忽略 update-alternatives --config php 没执行
• windows 用户常把 WAMP/XAMPP 的 bin 目录加进了 PATH，但该目录下 php.exe 是旧版

临时绕过 PHP 版本检查（仅调试用）

如果你只是想快速验证是不是纯版本问题，且确定代码逻辑兼容，可用 --ignore-platform-req=php 跳过校验：

立即学习“PHP免费学习笔记（深入）”；

composer install --ignore-platform-req=php

但这是权宜之计，不能解决根本问题，也不适用于 CI/CD 或生产部署。尤其当依赖中包含 PHP 8.1+ 的语法（如枚举、match 表达式）时，运行时仍会 fatal Error。

• 更安全的临时方式是显式指定 PHP 路径：/usr/local/bin/php8.2 composer.phar install
• 永远不要在 composer.json 中删掉 "php" 约束字段来“解决”问题

永久修复：让 php 命令指向正确版本

目标是让终端输入 php -v 显示的版本与项目要求一致。操作取决于你的环境：

• Mac + Homebrew：brew unlink php && brew link --force php@8.2，然后检查 which php
• ubuntu/debian：sudo update-alternatives --set php /usr/bin/php8.2（先用 update-alternatives --list php 确认路径）
• Windows：修改系统环境变量 PATH，把新版 PHP 目录（如 C:php-8.2）移到旧版路径之前，重启终端
• 所有平台：执行 hash -r（Linux/macos）或关闭重开命令行（Windows），清除 shell 命令缓存

改完务必再跑一遍 php -v 和 composer --version，确认两者都加载了预期的 PHP SAPI。

CI/CD 或 docker 中的常见漏点

本地修好了，但 gitHub Actions、gitlab CI 或 docker build 依然失败？大概率是镜像里 PHP 版本没对齐。比如用了 composer:2 官方镜像，它默认基于 PHP 8.2，但你项目 require php:8.3 就会挂。

• Dockerfile 中别只写 FROM composer:2，要明确 FROM composer:2.5-php8.3
• github Actions 中，shivammathur/setup-php 必须指定 php-version: '8.3'，且 extensions 要匹配本地启用的模块
• 某些共享主机或 paas 平台（如 laravel Forge）需在面板中单独设置“CLI PHP version”，和 Web Server 的 PHP 版本是分开的

最隐蔽的问题：PHP CLI 和 Web Server 使用不同配置文件（php.ini），导致 extension=openssl 在 CLI 下被注释掉 —— 这会让 Composer 直接退出，错误信息却不提扩展，只报“failed to open stream”。遇到卡在下载阶段，先跑 php -m | grep openssl。