Laravel9(PHP8.1)安装maatwebsite/excel依赖报错问题排查

问题根因 #

从执行composer require maatwebsite/excel返回的报错信息，可直接定位两个阻塞安装的核心问题：

• maatwebsite/excel 3.1.0~3.1.25版本仅支持PHP 7.x，与当前使用的PHP 8.1.6版本不兼容
• 所有兼容PHP 8的maatwebsite/excel版本，其依赖的phpoffice/phpspreadsheet包强制要求PHP开启ext-gd图形扩展，当前PHP环境未启用该扩展

解决步骤 #

永久修复方案（推荐，生产/开发环境均适用） #

1. 打开XAMPP环境下的PHP配置文件，默认路径为C:\xampp\php\php.ini
   如果不确定CLI模式下PHP实际加载的配置文件路径，先在终端执行php --ini查看对应路径，避免改错配置文件
2. 在打开的php.ini文件中搜索扩展配置项：
   • PHP 8.x版本搜索;extension=gd
   • 旧版本PHP搜索;extension=php_gd2.dll
     找到后删除行首的注释分号;，保存文件
3. 重启XAMPP的Apache服务，让配置生效
4. 终端执行以下命令验证gd扩展是否开启成功，返回gd即为开启正常：

php -m | findstr gd

（Windows环境用findstr，Linux/Mac环境把findstr换成grep即可）
5. 回到项目目录，重新执行安装命令，推荐直接指定兼容Laravel 9和PHP 8.1的稳定版本：

composer require maatwebsite/excel:^3.1.40

临时绕过方案（仅本地快速测试用，不推荐生产环境） #

如果暂时不需要配置gd扩展，仅做代码层面的依赖安装，可以在composer命令后添加参数跳过平台扩展校验：

composer require maatwebsite/excel --ignore-platform-req=ext-gd

注意：该方法只是跳过安装时的校验，实际运行Excel导入、导出功能时仍然依赖gd扩展，未开启扩展的情况下调用相关方法会直接报运行时错误，正式环境必须按永久修复方案开启对应扩展。

版本排查辅助命令 #

如果自动匹配版本一直失败，可以执行以下命令让composer自动排查所有可兼容的版本：

composer require maatwebsite/excel:*

内容的提问来源于stack exchange，提问作者Gymnastiar Ramadhan