使用 composer check-platform-reqs --no-dev 命令快速定位缺失的 PHP 扩展，精准校验平台依赖并标识 MISSING 项，专注于运行时必需扩展，同时兼容 config.platform.ext-xxx 配置声明。
Composer install 报错提示“ext-xxx missing”如何快速定位缺失的 PHP 扩展
在执行 composer install 或 update 命令时，若遇到类似 The requested PHP extension ext-gd is missing from your system 的错误提示，这是一个常见问题。其根本原因在于当前 PHP 运行环境未能满足 composer.json 文件或其依赖包中声明的扩展要求。此时，无需逐条分析冗长的报错信息，有一个更高效的解决方案。
请在项目根目录下直接运行以下命令：
composer check-platform-reqs --no-dev
此命令的作用是全面检查所有平台依赖，包括 PHP 版本、扩展模块及系统配置等要求，并清晰列出状态为 MISSING 的缺失项。添加 --no-dev 参数旨在过滤开发依赖，让您集中精力解决生产环境所必需的 PHP 扩展问题。
- 若项目出于兼容性或持续集成考虑，在
composer.json中通过config.platform.ext-xxx手动声明了某个扩展的存在，check-platform-reqs命令同样会校验该扩展在实际环境中是否真实安装。 - 请注意一个关键细节：此命令仅检测扩展模块名称是否出现在
php -m的输出列表中。它不会验证扩展文件是否已在php.ini中正确启用（例如，gd.so文件存在，但extension=gd配置行被注释）。 - Windows 用户若遇到
ext-openssl报缺失，请先保持冷静。PHP for Windows 发行版通常默认已包含 OpenSSL 扩展，问题很可能源于php.ini文件中extension=openssl这一行未被取消注释。
为何 php -m 未显示扩展而 phpinfo() 页面却存在
这是一个非常典型的问题，通常是由于命令行接口与 Web 服务使用了不同的 php.ini 配置文件所致。Composer 在命令行环境下运行，仅识别 CLI 对应的配置文件；而浏览器访问 phpinfo() 所显示的，则是 Web 服务器加载的配置。
要明确当前状况，首先查看命令行 PHP 正在使用的配置文件路径：
php --ini
命令输出将类似于：Loaded Configuration File: /etc/php/8.2/cli/php.ini。而您的 Web 服务器很可能使用的是 /etc/php/8.2/apache2/php.ini 或 /etc/php/8.2/fpm/php.ini。
- 解决方案是：编辑 CLI 所使用的
php.ini文件（请务必确认路径），确保所需扩展的配置行未被注释，例如extension=mbstring。 - 对于需要通过 PECL 或系统包管理器安装的扩展，如
redis、igbinary，流程分为两步：首先安装对应的共享对象文件（例如执行sudo apt install php-redis），然后在php.ini中启用它。若仅配置而未安装，则会遇到 “unable to load dynamic library” 错误。 - 修改
php.ini后，CLI 进程需要重新加载配置（通常只需开启新的终端窗口），无需重启 Web 服务器。验证时，直接在新终端中运行php -m | grep redis查看是否有输出即可。
Composer 扩展名与实际 PHP 模块名不一致如何处理
Composer 在 composer.json 中声明扩展依赖时，使用的是标准化名称，例如 ext-intl、ext-bcmath。然而，php -m 命令列出的模块名有时存在细微差异：
ext-intl→ 实际模块名为intlext-bcmath→ 实际模块名为bcmathext-opcache→ 实际模块名为opcache（注意并非zend opcache）ext-apcu→ 实际模块名为apcu（请勿与旧版apc混淆）ext-gd→ 在 CLI 环境下，模块名通常为gd，极少数情况下可能是gd2，但优先确认gd即可
若不确定系统中已加载了哪些扩展，可使用以下命令进行精准查看。此方法比 php -m 更底层、更可靠，尤其适用于某些有条件加载的扩展：
php -r "print_r(get_loaded_extensions());"
如何在 CI/CD 环境中高效配置 PHP 扩展避免常见问题
在 Docker 或 GitHub Actions 等持续集成与部署环境中，PHP 扩展缺失问题尤为常见。其根源在于所使用的基础镜像（如 php:8.2-cli）为了保持轻量，默认仅安装最核心的扩展。
无需再通过 apt install 手动逐一安装扩展，效率较低。对于 Docker 环境，推荐使用官方镜像提供的工具命令来批量安装并启用扩展。对于源码编译的核心扩展，可使用：
docker-php-ext-install mbstring gd intl bcmath opcache
对于需要通过 PECL 安装的扩展（例如 redis、grpc），流程稍多一步：
pecl install redis && docker-php-ext-enable redis
- 请注意，
docker-php-ext-install仅负责安装 PHP 扩展，不会自动处理系统级的依赖库。例如，在安装gd扩展前，需确保系统中已安装libfreetype6-dev等开发包。 - 若您使用 GitHub Actions，操作更为简便。直接使用社区维护的
shivammathur/setup-phpAction，它可通过参数直接指定需要启用的扩展列表，比自行编写 apt 和 docker-php-ext 命令更为稳定和便捷。 - 最后提醒使用 XAMPP、MAMP、WAMP 等集成环境进行本地开发的用户：通过图形界面启用或禁用扩展，通常仅影响 Web 服务器的 PHP 模块，命令行 PHP 配置是独立的。因此，修改图形界面设置后，请务必同步修改集成环境自带的 CLI PHP 的
php.ini文件。
归根结底，解决 ext-xxx missing 问题的核心并非盲目安装。关键在于理清三个环节：Composer 运行时使用的是哪个 PHP 可执行文件？该 PHP 加载了哪一份 php.ini 配置文件？以及这份配置最终加载的扩展列表具体是什么？厘清这三点，问题自然迎刃而解。
