跳转到主内容
趣航编程网 - 趣学编程,启航技术之路!

Composer平台检查:自动检测PHP版本与扩展兼容性

composer install 成功但运行报 Class not found,因 Composer 默认仅校验 composer.json 显式声明的 PHP/扩展约束,不扫描代码实际调用的函数、类或 INI 配置;需用 composer check-platform-reqs(Composer 2.2+)检查全部依赖的平台要求,并结合 composer dump-autoload -v 排查自动加载失效。 Composer 本身不自动检测平台兼容性,
platform-check
和
check-platform-reqs
都是手动触发命令,不会在
install
或
update
时默认运行。 为什么 composer install 成功了,但项目一跑就报 Class not found? 因为 Composer 默认只校验
composer.json
中显式声明的
php
和
ext-*
约束,不扫描代码实际调用的函数或类。常见漏检点:
ext-redis
已加载,但
redis.session.locking_enabled
这类 INI 配置缺失 →
platform-check
不管 ini 设置
ext-gd
存在,但没编译 PNG 支持 → 扩展存在,功能残缺,
platform-check
无法识别 某包在源码里用了
str_contains()
(PHP 8.1+),但
composer.json
只写了
"php": "^7.4"
→ Composer 不做语法级扫描 用哪个命令检查最贴近真实运行环境? 优先用
composer check-platform-reqs
(Composer 2.2+),它读取的是项目所有依赖(含传递依赖)的
require
字段,比
composer diagnose
更准。注意区别:
composer diagnose
只查 Composer 自身运行依赖(如
json
、
mbstring
、
curl
),不看项目 require 的
ext-gd
等
composer platform-check
默认只检查顶层
require
,加
--with-dependencies
才递归检查全部依赖项的平台要求
composer install --dry-run
会尝试解析整个依赖图并触发 autoloader 初始化逻辑,比纯静态检查更早暴露运行时问题 本地和 CI 环境检查结果不一致?先确认 PHP 二进制是否统一 报错说
ext-zip
缺失,但
php -m | grep zip
能看到 —— 这几乎一定是 Composer 调用的 PHP CLI 和你手动执行的不是同一个二进制。 PHP 8.5.5 PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑,通过深度错误修复、底层性能微调以及安全加固,旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范,不包含破坏性变更。 下载 立即学习 “ PHP免费学习笔记(深入) ”; 运行
which php
和
composer config --global bin-dir
,确认 Composer 启动时用的是哪个
php
用完整路径验证:比如
/usr/bin/php -m | grep zip
或
/opt/homebrew/bin/php -v
macOS 上 Homebrew 安装的 PHP 常因 PATH 顺序导致 CLI 默认用系统旧版;Windows 用户注意 XAMPP、WAMP、独立 PHP 目录可能混用 Docker 场景下,
composer:2
镜像不含 PHP,必须基于
php:8.1-cli
这类基础镜像构建,否则
check-platform-reqs
在构建阶段运行,而容器运行时 PHP 版本不同 怎么让检查真正起作用,而不是走个过场? 关键不是多跑几个命令,而是把检查嵌入到流程里,并避免配置干扰: 删掉
composer.json
里的
"platform"
段(除非 CI 明确需要“降级模拟”),否则
check-platform-reqs
校验的是假定环境,不是真实 PHP CI 中加一行:
composer platform-check --no-dev
,排除
require-dev
干扰,聚焦生产环境约束 用自定义脚本兜底:
bin/check-env.php
可检查
function_exists()
、
defined()
、INI 配置值等,
platform-check
做不到的它都能补上 不要用
--ignore-platform-reqs
临时绕过——它跳过检查,但装上的包在运行时大概率崩,排查成本更高 最容易被忽略的一点:
composer.lock
文件里存了生成时的 PHP 版本信息,但它不会阻止你在更低版本上强行
install
。所以不能靠 lock 文件保兼容,每次切换 PHP 环境后,都得重新跑一遍
check-platform-reqs
或
platform-check
。

相关文章