解决Composer安装扩展包时遇到的“Extension not loaded”问题

composer require 成功但扩展报“Extension not loaded”，是因为Composer只管理php代码依赖，不启用PHP扩展；需通过php -m、php –ini、phpinfo()确认扩展是否真实加载，并在对应php.ini中启用或系统安装对应扩展。

为什么 composer require 成功但扩展仍报 “Extension not loaded”

Composer 只负责下载和自动加载 PHP 代码，它不启用 PHP 扩展。所谓 “Extension not loaded”，本质是 PHP 运行时没加载对应扩展（如 ext-redis、ext-gd），和 Composer 安装包是否成功完全无关。常见错觉是“我装了 phpredis/phpredis，Redis 就该能用”，但这个包只是 PHP 封装，底层仍依赖已启用的 redis 扩展。

• 检查扩展是否启用：运行 php -m | grep redis（把 redis 换成你要查的扩展名）
• 确认 CLI 和 Web SAPI 使用的是同一份 php.ini：执行 php --ini 和 phpinfo() 中的 “Loaded Configuration File” 路径可能不同
• 扩展名 ≠ 包名：例如 ext-imagick 对应扩展是 imagick，不是 imagick.so 或 php-imagick

如何确认并启用缺失的 PHP 扩展

先定位你缺的是哪个扩展 —— 看 Composer 的 require 语句或 composer.json 里写的 ext-xxx，比如 "ext-zip": "*" 表示需要 zip 扩展。

• linux（apt）：sudo apt install php-zip（ubuntu/debian）或 sudo yum install php-pecl-zip（centos/RHEL 7+）
• macos（Homebrew）：brew install php@8.2-zip（版本需匹配你的 PHP）
• windows：编辑 php.ini，取消注释 ;extension=zip → 改为 extension=zip；注意路径是否正确（如 extension=php_zip.dll）
• 重启服务：CLI 不用重启，但 apache/nginx + PHP-FPM 必须 reload，例如 sudo systemctl reload php8.2-fpm

遇到 “ext-xxx is missing” 但系统已安装扩展怎么办

典型原因是 PHP 多版本共存或配置未生效。尤其在 docker、laravel Valet、MAMP 等环境中，CLI 和 Web 使用的 PHP 实例经常不一致。

• 运行 which php 和 php -v，确认 CLI 当前用的是哪个 PHP 版本
• 在 Web 页面中新建 info.php，写

  ，查看 “Loaded Configuration File” 和 “extension_dir”

• 对比两处的 extension_dir 是否指向同一目录；若不一致，CLI 可能找不到 .so 文件
• 手动验证扩展是否可加载：php -r "var_dump(extension_loaded('gd'));"，返回 bool(true) 才算真正可用

使用 composer require 前快速检查环境兼容性

别等报错再排查。Composer 提供内置命令提前验证扩展依赖是否满足：

composer check-platform-reqs

它会列出所有 platform 依赖（含 ext-* 和 lib-*），并标出缺失项。如果输出里有红色 MISSING，就说明必须先解决扩展问题，否则即使强制 --ignore-platform-reqs 安装，运行时也必然失败。

• 临时绕过检查（仅测试用）：composer require some/package --ignore-platform-reqs，但上线前必须补全扩展
• 长期方案：在 composer.json 的 config.platform 下模拟目标环境，避免本地开发环境“太全”导致线上部署失败

扩展是否加载，永远取决于 PHP 解析器本身，而不是 Composer。哪怕你把整个 vendor 目录复制过去，只要 php -m 里没有那个 ext-xxx，运行时照样报错 —— 这点最容易被忽略。