Composer 启动依赖系统 php 命令，若 php -v 不可用或缺失 json/mbstring/openssl 等扩展，则 composer --version 必报错；composer diagnose 不校验项目平台要求，应改用 composer check-platform-reqs。
Composer 本身是 PHP 写的命令行脚本，不是独立二进制程序——它必须由 PHP 解释器来执行，所以没有可用的 php 命令，composer 就根本启动不了。
为什么 composer --version 都报错？先查 php 是否真可用
很多人卡在第一步：终端输入 composer --version 提示 command not found 或直接报错，其实问题不在 Composer，而在 php 本身没配好。
-
php -v必须能输出版本号（推荐 ≥ 8.1）；如果报command not found，说明系统 PATH 没包含 PHP 可执行文件路径 - Windows 用户常见于 XAMPP/WAMP 的
php.exe没加进系统环境变量；macOS/Linux 用户要注意 Homebrew 安装的 PHP 路径（如/opt/homebrew/bin/php）是否已写入 shell 配置 - 即使
php -v成功，也得确认 CLI 模式下关键扩展已启用：json、mbstring、openssl、curl、zip—— 缺一个，composer启动时就会中断，错误可能表现为Could not open input file: composer.phar这类误导性提示
composer diagnose 显示 OK，但 install 还是失败？它根本不看你的依赖要求
composer diagnose 只检查 Composer 自己能不能跑：PHP 版本够不够它自己用、composer.json 是不是合法 JSON、vendor/ 目录能否写入、能不能连上 Packagist。它完全不读你 require 里写的 "php": "^8.2"，也不管 "ext-redis": "*" 在不在当前环境里。
- 典型脱节场景：
composer.json要求ext-redis，但php -m输出里没有redis——diagnose一声不吭，install直接中止 -
config.platform.php锁成"7.4.33"，而你本地是 PHP 8.2 ——diagnose觉得一切正常，但依赖解析会崩，报Your requirements could not be resolved - 真正该用的是
composer check-platform-reqs，它才扫描require和所有已安装包的平台约束，并和当前 CLI 环境比对
为什么 PHP 8.x 下必须用 Composer 2.2+？旧版会直接 parse error
Composer 1.x 用的是 PHP 7 风格语法，遇到 PHP 8 的联合类型（string|int）、构造函数属性提升（public function __construct(public string $name)）等特性，会直接报 ParseError: syntax error, unexpected token "string"。
立即学习“PHP免费学习笔记（深入）”；
- Composer 2.2+ 才原生支持 PHP 8.0–8.3 全部语法特性；当前稳定版
v2.7.7要求 PHP ≥ 7.2，但实际建议搭配 PHP 8.1+ 使用 - 别信“装了最新 PHP 就万事大吉”——
composer --version输出如果是1.x，必须重装；官方推荐安装命令是php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php --install-dir=/usr/local/bin --filename=composer - 某些共享主机禁用
proc_open()，会导致 Composer 启动失败；这种环境下只能本地装好再上传vendor/和composer.lock
platform 字段写错位置或格式，等于没写
很多人想锁定 PHP 版本做依赖解析，却把 "platform": {"php": "8.2.12"} 塞进 config 块里，结果完全不生效——platform 必须是 composer.json 的根级字段，和 require 并列。
- 错误写法：
"config": { "platform": { "php": "8.2" } }→ Composer 忽略 - 正确写法：
"platform": { "php": "8.2.12", "ext-gd": "8.2.12" }→ 注意版本号必须完整，"^8.2"或"8.2"都无效 - 命令行参数
--platform=php:8.2.12优先级更高，适合 CI 构建时临时覆盖，且不影响composer.lock内容 -
require中的"php": "^8.1"才是项目真实运行契约；platform只是模拟环境供解析用，二者不能互换
最容易被忽略的一点：Composer 的行为取决于它调用的 php 命令，而不是你 Web 服务器用的 PHP 版本。Mac 上多套 PHP 环境共存（Homebrew / MAMP / 系统自带），Linux 上 which php 和 php -v 输出不一致，都可能导致 install 成功但 runtime 报错——因为加载的是另一套 PHP 的扩展和配置。
