composer check-platform-reqs --no-dev 检查 composer.json 中 require 声明的 PHP 版本、扩展及版本是否满足,忽略 require-dev,专用于部署前环境预检,避免运行时 Class not found 等问题。

composer check-platform-reqs --no-dev 检查什么
它只检查 require(非 require-dev)中声明的 PHP 扩展、PHP 版本、扩展版本等是否满足,忽略所有开发依赖的平台约束。部署时用这个命令,能快速确认当前服务器环境是否跑得起来生产代码。
常见错误现象:本地 composer install 成功,但上线后报 Class not found 或 Call to undefined function mb_strlen() —— 很可能就是 mbstring 没装,而它只在 require 里(比如被 symfony/polyfill-mbstring 间接依赖),--no-dev 才会暴露这个问题。
-
--no-dev不影响已安装的包,只控制「校验范围」 - 它不读取
composer.lock,纯看composer.json的require和平台配置(如config.platform.php) - 若项目用了
config.platform模拟低版本环境,check-platform-reqs会按该模拟值校验,不是真实服务器 PHP 版本
为什么不能只用 composer install --no-dev 来代替
composer install --no-dev 会跳过 require-dev 包的安装,但不会主动报错告诉你「ext-redis 缺失」—— 它只在安装扩展相关包时失败;而 check-platform-reqs 是专门做平台层预检的,失败即中断,适合 CI/CD 流水线卡点。
-
install --no-dev可能因网络、权限、包冲突等失败,掩盖真正的平台缺失问题 -
check-platform-reqs输出简洁,每行一个未满足项,例如:ext-gd is missing、php (>=8.1) is required, but 8.0.30 is installed - 某些扩展(如
ext-sodium)在 PHP 7.2+ 是内置的,但旧系统可能被编译掉,check-platform-reqs能直接揪出
CI/CD 中怎么安全集成这个命令
把它放在部署前的「环境校验」阶段,而不是和 composer install 合并在一步里。一旦失败,立刻终止流程,避免部分安装后状态混乱。
- 推荐写成独立脚本步骤:
composer check-platform-reqs --no-dev || exit 1 - 如果服务器 PHP 版本由容器或 PaaS 控制(如 Heroku、Laravel Vapor),仍需运行——它们可能默认禁用某些扩展
- 注意:某些共享主机禁用
dl()或限制extension_dir,check-platform-reqs无法检测这类运行时限制,只能靠后续php -m | grep redis辅助验证
容易被忽略的 config.platform 干扰
如果 composer.json 里写了 "config": {"platform": {"php": "7.4.33"}},check-platform-reqs 会假装当前 PHP 是 7.4.33,即使你实际用的是 PHP 8.2 —— 这会导致「明明扩展已装却报错」或「该报错却没报」。
- 部署脚本中应显式清除 platform 配置:
composer check-platform-reqs --no-dev --no-plugins --no-cache -
--no-plugins防止第三方插件修改平台判断逻辑(如hirak/prestissimo旧版有干扰) - 最稳妥做法:在部署目标环境上,用
php -v和php -m手动核对关键扩展,再跑check-platform-reqs










