离线安装时 composer install 报 “extension missing” 错误，需用 --ignore-platform-reqs 跳过扩展检查，或在 composer.json 中配置 platform 伪声明扩展；但运行时仍需确保真实环境已启用对应 php 扩展。
离线安装时 composer install 报 “extension missing” 错误怎么办
离线环境下，composer install 会照常读取 composer.lock 并校验 PHP 扩展依赖（比如 ext-gd、ext-mbstring），但不会真正加载扩展——它只是检查 php -m 输出里有没有。一旦本地 PHP 缺少某个声明了的扩展，就直接中断，哪怕你根本用不到那段代码。
常见错误现象：Your requirements could not be resolved to an installable set of packages. 或更直白的：The requested PHP extension ext-xxx is missing from your system.
- 别试图在离线机上装扩展——没网络，
pecl install或系统包管理器都走不通 - 临时禁用扩展检查：加
--ignore-platform-req=ext-xxx参数，多个就重复写，例如--ignore-platform-req=ext-gd --ignore-platform-req=ext-mbstring - 更省事的做法是忽略所有扩展和 PHP 版本约束：
--ignore-platform-reqs（注意是复数）——这在纯离线部署脚本里最常用 - ⚠️ 这个参数不解决运行时问题，只跳过安装阶段校验；如果代码真调用了
gd_info()而没装gd，运行时照样Fatal error
为什么 composer create-project 在离线时也会失败
因为 create-project 底层会先 git clone 或下载 dist 包，再执行 install，两步都可能触发平台约束检查。即使你已把完整 vendor 打包带过去，它默认仍要重跑 install 流程。
- 离线用
create-project前，务必加--no-install --prefer-dist，先拉下项目骨架 - 然后手动复制好已提前在有网环境生成的
vendor/目录（确保和composer.lock完全匹配） - 最后用
composer install --no-dev --optimize-autoloader --ignore-platform-reqs补全 autoload 并跳过检查 - 不推荐用
--no-scripts来绕过 post-install-cmd——有些脚本是生成配置必需的，跳过反而导致启动失败
platform 配置能替代 --ignore-platform-reqs 吗
可以，而且更可控。在 composer.json 里加 "platform" 段，相当于“骗” Composer 说：“我有这些扩展”，但它不检查真实环境。
{
"config": {
"platform": {
"php": "8.1.0",
"ext-gd": "1.0",
"ext-mbstring": "1.0",
"ext-openssl": "1.0"
}
}
}
- 这个配置只影响当前项目，比全局
--ignore-platform-reqs更安全 - 值填什么不重要（字符串即可），Composer 只认键名存在与否
- 如果项目里用了
ext-sodium但你的 PHP 是 7.2 编译时没开，填了"ext-sodium": "1.0"也拦不住运行时报错——它只管安装阶段 - CI/CD 打包时建议用这种方式，避免运维同学记不住加参数
离线部署后运行时才发现扩展缺失，怎么快速定位
Composer 不报错 ≠ 代码能跑。最典型的坑是：--ignore-platform-reqs 让安装过了，但某段逻辑调用了 json_encode()（需要 ext-json），而你的 PHP 是最小化编译的，压根没启这个模块。
- 上线前，在目标机器跑一遍：
php -m | grep -E '^(gd|mbstring|curl|json|openssl|xml)$'，对照composer.json的require和实际代码使用范围 - 用
grep -r 'function_exists.*gd' .或grep -r 'imagecreatefrom' .快速扫出硬依赖 - 如果项目用了 Laravel，注意
storage:link依赖ext-symlink（其实是系统能力，但 Composer 会当扩展查）——这种属于“伪扩展依赖”，platform配置无效，得看系统权限
离线部署最麻烦的从来不是 Composer 装不上，而是你以为跳过了检查就万事大吉，结果第一笔请求就 core dump。多花两分钟核对 php -m 输出，比重启三次容器省时间。
