答案是PHP环境缺失扩展,需确认php.ini启用、系统安装对应扩展包并匹配版本;运行composer check-platform-reqs精准定位,php -m验证加载,按PHP版本号安装(如php8.2-dom),避免跳过检查埋雷。

直接结论:不是包没装上,而是 PHP 环境缺扩展——composer require 报 “ext-xxx is missing” 时,95% 的问题出在 php.ini 没启用、系统没装对应扩展包,或版本不匹配。
为什么 composer require 会卡在 ext-* 缺失?
Composer 在执行 require 前,会先解析整个依赖树,并检查所有包(包括你刚加的、它间接依赖的、甚至 root composer.json 里写的)声明的 ext-* 要求。只要其中任意一个扩展未加载或版本不符,就会中断并报错,不会继续下载或安装任何包。
常见诱因包括:
- 本地开发机用的是 PHP 8.1,但
composer.json写了"ext-dom": ">=3.0"(DOM 扩展 3.0 是 PHP 8.2+ 才带的) - 宝塔面板里 PHP 版本选了 8.1,但扩展管理页没勾选
curl或mbstring,php -m也查不到 - CI 脚本里用了
php:8.1-cli镜像,但该镜像默认不带ext-pdo_mysql,也没跑docker-php-ext-install pdo_mysql
快速定位缺失扩展的三步法
别猜,用 Composer 自带命令精准暴露问题:
- 运行
composer check-platform-reqs—— 它会列出所有未满足的ext-*和 PHP 版本偏差,比看报错日志快得多 - 运行
php -m | grep -E "(dom|curl|mbstring|json|xml|pdo)",确认关键扩展是否真在已加载列表里 - 运行
composer show --platform,查看 Composer 当前“认为”你环境支持哪些扩展(注意:它受config.platform干扰)
如果 check-platform-reqs 显示 ext-dom 缺失,但 php -m 有 dom,大概率是 CLI 和 Web 使用了不同 php.ini —— 查 php --ini 确认路径。
Ubuntu/Debian 下补装 ext-dom、ext-curl 等常见扩展
必须按你实际的 PHP 版本号安装,否则白装:
- 先查版本:
php -v(比如输出PHP 8.2.10) - 更新源:
sudo apt update - 装扩展:
sudo apt install php8.2-dom php8.2-curl php8.2-mbstring php8.2-xml php8.2-zip(把8.2换成你的版本) - 验证:
php -m | grep dom应有输出;若无,检查是否需重启php-fpm或 Apache/Nginx
注意:php-curl 这类包名在 Ubuntu 22.04+ 默认指向系统默认 PHP 版本,如果你用的是多版本共存(如 Ondřej PPA),务必带版本号安装,否则可能装到 8.1 上而 CLI 在用 8.2。
跳过检查不是修复,是埋雷
--ignore-platform-reqs 或 --ignore-platform-req=ext-curl 能让 require 成功,但后果很实在:
- 后续运行时遇到
Class 'DOMDocument'找不到、curl_init()未定义,就是它干的 - CI 流水线里出现这条参数,等于放弃环境一致性校验,上线后故障率翻倍
- 某些框架(如 Laravel 11+)在启动时还会二次校验扩展,跳过 Composer 检查也拦不住运行时报错
真正该做的,是在部署文档里明确写清 ext-dom, ext-pdo, ext-xml 等最低要求,并用 check-platform-reqs 做准入检查。开发机和生产环境差一个扩展,就不是“差不多能跑”,而是“随时崩”。











