确认系统是否缺少PHP扩展需先用php -m | grep xxx检查是否已加载，若无再通过php --ini定位对应php.ini并启用extension=xxx；注意CLI与Web服务器使用不同配置文件，Ubuntu/Debian需安装php<ver>-xxx包，macOS用Homebrew或pecl安装时需确保extension_dir路径正确。

确认系统中是否真的缺少该 PHP 扩展

这个错误不总意味着扩展没装——更常见的是 php.ini 没启用，或 Composer 用的不是你认为的那个 PHP 版本。先运行：

php -m | grep xxx

（把 xxx 替换为报错里的扩展名，比如 gd、mbstring），看是否在列表里。如果没输出，再查 PHP 配置路径：

php --ini

，确认 Loaded Configuration File 指向的 php.ini 是否已启用该扩展（如存在 extension=mbstring 或 extension=gd.so 等行，且未被注释）。

区分 CLI 和 Web Server 使用的不同 php.ini

Composer 在终端运行，走的是 CLI SAPI，而浏览器访问走的是 Apache/FPM SAPI，它们可能加载不同的 php.ini。即使你在 /etc/php/8.2/apache2/php.ini 里启用了 ext-gd，CLI 仍可能读取 /etc/php/8.2/cli/php.ini ——这个文件里很可能没开。检查并同步修改 CLI 对应的 php.ini，改完后务必运行：

php -m | grep gd

验证 CLI 环境是否生效。

Ubuntu/Debian 下安装常见扩展的命令规律

Linux 发行版通常把 PHP 扩展打包成独立包，命名格式固定：php-<version>-<extension-name></extension-name></version>。例如：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 缺 ext-mbstring → 安装 php8.2-mbstring
• 缺 ext-gd → 安装 php8.2-gd
• 缺 ext-pgsql → 安装 php8.2-pgsql

注意：版本号必须和 php -v 输出一致；安装后无需手动改 php.ini，包管理器会自动配置好。装完别忘了验证：

php -m | grep mbstring

macOS 使用 Homebrew 时的典型陷阱

Homebrew 安装的 PHP（如 php@8.2）默认不带所有扩展，需单独安装对应扩展包，但命名规则不同：

• ext-intl → brew install icu4c + 确保 php.ini 中有 extension=intl
• ext-opcache → 通常已内置，但可能被注释，取消注释即可
• ext-redis → pecl install redis，然后加 extension=redis.so 到 php.ini

特别注意：pecl 安装的扩展路径可能不在默认 extension_dir 下，可用

php -i | grep extension_dir

查看，再把生成的 .so 文件复制过去，或直接在 php.ini 中写绝对路径，如：extension=/opt/homebrew/lib/php/pecl/20220829/redis.so。

立即学习“PHP免费学习笔记（深入）”；