composer 通过 require 声明 ext-* 依赖并配合 config.platform 强制校验 php 扩展是否启用，防止运行时错误；platform 模拟目标环境以确保依赖解析准确，扩展名须与 php -m 输出完全一致（小写、下划线）。

composer.json 里怎么声明 PHP 扩展依赖

Composer 不会自动检测或安装 PHP 扩展，但能通过 require 和 platform 配置强制校验扩展是否已启用。核心是让 composer install 或 composer update 在扩展缺失时直接报错，而不是等到运行时报 class not found 或 Call to undefined function。

常见错误是只写 "ext-curl": "*" 却没配 config.platform，结果 CI 环境或新服务器上因 PHP 编译参数不同（比如没带 --with-curl）导致构建通过、运行失败。

• "ext-mbstring": "*" 表示必须启用 mbstring 扩展，版本号不重要（PHP 扩展无语义化版本）
• "ext-redis": "^5.3" 是无效写法 —— 扩展版本号由 PHP 模块本身决定，Composer 只认 * 或留空
• 若项目依赖 ext-gd 但只在 PNG 处理逻辑中用到，可考虑用 class_exists('GdImage') 运行时判断，而非强声明进 composer.json

{     "require": {         "php": "^8.1",         "ext-curl": "*",         "ext-mbstring": "*",         "ext-openssl": "*",         "ext-json": "*",         "ext-pdo": "*",         "ext-pdo_mysql": "*"     },     "config": {         "platform": {             "php": "8.1.28"         }     } }

为什么需要 config.platform.php

本地开发环境 PHP 是 8.2，但生产环境锁定为 8.1.28 —— 如果不设 config.platform.php，Composer 会按本地版本解析依赖，可能装入仅兼容 8.2 的包（比如用了 match 表达式但没加 #[ReturnTypeWillChange]），或漏掉对旧版语法的兼容检查。

更关键的是：平台扩展也受 platform 影响。例如你本地有 ext-igbinary，但生产没有，又没在 require 中声明它，Composer 就不会报错。这时候必须靠 platform 显式“降级”声明可用扩展集，才能触发校验。

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

• config.platform 是模拟目标环境的“虚拟平台”，Composer 会据此判断哪些扩展/PHP 版本真正可用
• 它不影响实际运行时行为，只影响依赖解析和安装前检查
• CI 脚本中建议加上 composer install --no-dev --ignore-platform-reqs 仅用于生成锁文件，但正式部署必须去掉 --ignore-platform-reqs

扩展名大小写与拼写陷阱

PHP 扩展名区分大小写，且命名不统一：ext-pdo_mysql 不能写成 ext-pdo-mysql 或 ext-pdomysql；ext-iconv 在某些 Alpine 镜像中叫 ext-iconv，但 windows 下可能是 php_iconv.dll 对应 ext-iconv —— Composer 只认 php -m 输出的模块名小写形式。

查准名字最可靠的方式是执行：

php -m | grep -i curl # 输出：curl # 所以写 "ext-curl": "*" 
php --ri mbstring | head -1
输出：mbstring
所以写 "ext-mbstring": "*"

• ext-zip ≠ ext-zlib：前者操作 ZIP 文件，后者是压缩基础库，两者独立
• ext-pdo_pgsql 和 ext-pdo_sqlite 必须按实际数据库类型单独声明，ext-pdo 本身只是接口层，不提供驱动
• docker 用户注意：docker-php-ext-install 启用的扩展名，就是 Composer 要求的名称，比如 docker-php-ext-install pdo pgsql 后需声明 "ext-pdo": "*", "ext-pdo_pgsql": "*"

运行时扩展检测比 composer.json 更灵活

composer.json 声明是静态约束，适合构建期卡点；但有些扩展（如 ext-apcu、ext-opcache）属于性能优化项，缺失不影响功能，只降速。这类更适合运行时检测 + 日志告警，而不是阻断安装。

例如 laravel 的 appServiceProvider::boot() 中可加：

if (!extension_loaded('apcu')) {     Log::warning('APCu extension not loaded — cache performance may suffer'); }

• 扩展加载状态无法在 composer.json 中做条件声明（比如“有 apcu 就用，没有就 fallback 到 file cache”）
• 某些 SaaS 部署平台（如 Heroku、Laravel Vapor）限制扩展安装，硬声明会导致部署失败，此时应改用 function_exists() 或 extension_loaded() 动态适配
• ext-sodium 在 PHP 7.2+ 已内置，但部分旧编译版本仍需手动启用，声明时仍应保留 "ext-sodium": "*" 保证一致性

扩展依赖不是越全越好，关键是匹配运行环境真实能力。漏声明会埋 runtime Error，乱声明会让部署变脆弱。