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免费学习笔记（深入）”；
- 运行
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。
