composer diag 是排查 Composer 问题的首选命令，它检测 PHP 环境、扩展、网络连接、配置权限等，提示常见错误并给出修复建议，帮助快速定位环境或配置问题。
当你在使用 Composer 时遇到问题，比如无法安装依赖、更新失败或报错提示不明确，composer diag 是一个非常有用的内置命令。它能帮助你快速检查当前环境是否存在常见问题，涵盖网络连接、配置路径、PHP 设置等多个方面。
什么是 composer diag？
composer diag 命令会运行一系列自我诊断测试，检测你的系统是否满足 Composer 正常运行的基本条件。执行后，它会列出发现的问题并给出建议，例如权限错误、HTTPS 连接异常、配置文件缺失等。
这个命令不需要额外参数，直接在项目目录或任意位置运行即可：
composer diag
常见的诊断项和可能问题
以下是 composer diag 检查的主要内容及对应的解决方法：
1. PHP 版本与扩展检查
- Composer 会验证当前 PHP 版本是否符合最低要求（通常为 PHP 7.2+）
- 检查必需的扩展是否启用，如 json、phar、openssl、mbstring 等
- 若提示 openssl 扩展缺失，可能导致 HTTPS 请求失败
解决方式：编辑 php.ini 文件，取消对应 extension 的注释，例如：
extension=openssl
2. 平台设置与运行环境
- 确认操作系统类型、架构是否被支持
- 检测是否在兼容的 shell 或终端中运行（特别是在 Windows 上）
- 某些 CI/CD 环境中可能出现临时警告，需确保 PHP 可执行路径正确
3. 网络连接问题（特别是访问 packagist.org）
- 尝试通过 HTTPS 连接到 packagist.org 和 github.com
- 如果出现超时或 SSL 错误，可能是代理、防火墙或 CA 证书问题
- 国内用户常因网络原因连接缓慢或失败
可以尝试切换镜像源来绕过网络限制：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
4. 配置文件与目录权限
- 检查全局配置目录（如 ~/.composer）是否存在且可读写
- 确认 cache 目录权限是否正常，避免“Permission denied”错误
- Windows 用户注意路径中不要有中文或空格
修复权限问题示例（Linux/macOS）：
chmod -R 755 ~/.composer
结合其他命令一起使用更有效
单独运行 composer diag 能发现问题线索，但还需配合其他命令深入排查：
- composer clear-cache：清除缓存，解决因损坏缓存导致的安装失败
- composer show -v：查看详细输出，定位具体出错包
- composer self-update：确保 Composer 自身是最新版本
如果 diag 报告一切正常但仍无法工作，考虑使用 -vvv 参数运行主命令获取调试日志：
composer install -vvv
基本上就这些。运行 composer diag 是排查问题的第一步，它能帮你快速判断是环境配置问题还是项目本身的问题，节省大量调试时间。遇到报错别急着重装，先让它跑一遍诊断。
