Composer不管理系统级库，仅通过ext-声明PHP扩展依赖并用platform模拟环境约束；lib-需由系统包管理器手动安装，声明时应避免在require中使用lib-*。
Composer 本身不直接管理或安装系统级库（如 lib-curl、lib-xml、lib-mysqlclient），它只处理 PHP 包。所谓 “声明 lib-* 依赖”，实际是通过 platform 或 require 中的扩展名（如 ext-curl）来**声明运行时环境约束**，而非下载安装这些库。
理解 lib-* 的真实含义
在 Composer 生态中：
-
lib-curl不是可安装的 Composer 包，而是指系统已安装的 cURL 库（通常由操作系统包管理器提供，如apt install libcurl4或brew install curl） - PHP 扩展（如
ext-curl）才是 Composer 能识别并检查的依赖项 —— 它依赖于底层lib-curl，但本身由 PHP 编译或扩展管理器加载 - Composer 的
require字段中写"ext-curl": "*"是标准做法；写"lib-curl": "*"会被忽略（除非自定义仓库或插件支持，但官方不支持）
正确声明系统库依赖的方式
通过 composer.json 声明运行环境要求：
- 用
ext-*声明必需的 PHP 扩展："require": { "ext-curl": "*", "ext-xml": "*" } - 用
platform模拟或锁定底层系统库版本（仅用于构建/测试一致性）："config": { "platform": { "ext-curl": "7.85.0", "lib-iconv": "1.17" } }
⚠️ 注意：platform不会安装任何东西，只是让 Composer 在解析依赖时“假装”这些扩展/库存在且为指定版本 - 避免在
require中写lib-*—— Composer 不识别它们，会导致依赖解析失败或静默忽略
确保系统库真正可用的操作建议
Composer 只做检查，不负责安装系统库。你需要手动或通过部署流程保障：
- Linux：安装对应开发包（如 Ubuntu 上
sudo apt install libcurl4-openssl-dev php-curl），其中-dev包含编译 PHP 扩展所需的头文件 -
macOS：用 Homebrew 安装
curl和启用 PHP 扩展（如通过phpbrew或homebrew-php管理多版本） - Docker：在
Dockerfile中明确安装系统库和 PHP 扩展：RUN apt-get update && apt-get install -y libcurl4-openssl-dev \&& docker-php-ext-install curl - CI/CD：在构建脚本开头验证扩展是否加载：
php -m | grep curl或php -r "echo extension_loaded('curl') ? 'ok' : 'fail';"
常见误区与替代方案
不要试图用 Composer 替代系统包管理器：
- ❌ 错误：添加
"lib-curl": "^7.0"到require—— Composer 无法解析，会报错或跳过 - ❌ 错误：期望
composer install自动安装libpq或libjpeg—— 它不会也不该做这件事 - ✅ 正确思路：把系统库要求写进
README.md或.env.example；用docker-compose.yml或Vagrantfile声明完整运行栈；用composer check-platform-reqs验证当前环境是否满足platform和ext-*要求
基本上就这些。关键记住：Composer 管 PHP 包，系统库归操作系统管；你声明的是“需要什么”，不是“让我帮你装什么”。
