composer 不负责 c 扩展编译，失败主因是容器缺构建工具、php 头文件或扩展未启用；需在 dockerfile 中显式安装对应依赖并调用 pecl install 或 docker-php-ext-install 启用，多阶段构建须确保两阶段 php 版本与架构一致，且 platform 配置须匹配实际环境。
Composer 本身不参与 C 扩展的编译，所谓“静态编译”不是 Composer 的职责，而是 PHP 构建环境和 Docker 镜像层的事。你遇到的其实是：含 ext-* 依赖（比如 grpc、protobuf、amqp、redis 等需编译的扩展）的包，在 composer install 时失败或运行时报 Class not found —— 根本原因在于容器里缺编译工具链、PHP 头文件、或扩展未启用。
为什么 composer install 会卡在 grpc 或 redis 扩展上
这类包（如 grpc/grpc、phpredis/phpredis）在安装时会触发 pecl install 或调用 ./configure && make && make install，需要：
- 系统级构建工具：
gcc、make、autoconf、pkg-config - PHP 开发头文件：
php-dev（Debian/Ubuntu）或php82-devel（Alpine） - 对应扩展的依赖库：
libgrpc-dev、openssl-dev、zlib-dev等 - PHP 配置中已启用该扩展（
extension=grpc.so），否则composer install可能跳过或报 autoload 错误
常见错误现象包括：configure: error: cannot find ssl headers、make: command not found、PHP Warning: Module 'grpc' already loaded（重复加载）、或安装后 php -m | grep grpc 查不到。
Dockerfile 中必须显式安装编译依赖，不能靠宿主机
别指望 composer install 自动解决底层编译问题。你得在 RUN 指令里提前装好整套工具链，并确保与目标 PHP 版本严格对齐：
- Debian/Ubuntu 基础镜像（如
php:8.2-cli）：加apt-get update && apt-get install -y gcc make autoconf pkg-config php8.2-dev libgrpc-dev libssl-dev zlib1g-dev - Alpine 镜像（如
php:8.2-cli-alpine）：加apk add --no-cache build-base php82-dev grpc-dev openssl-dev zlib-dev（注意 Alpine 包名带版本号） - 装完必须
docker-php-ext-install或pecl install显式启用扩展，例如：pecl install grpc && docker-php-ext-enable grpc - 若扩展需额外配置（如
grpc要设grpc.enable_fork_support=1），得写进php.ini或用echo "grpc.enable_fork_support=1" >> /usr/local/etc/php/conf.d/grpc.ini
漏掉任意一项，composer install 就可能静默跳过该包，或在运行时才暴露 Class not found。
多阶段构建下，编译必须放在 builder 阶段且保持环境一致
如果你用多阶段构建，千万别把编译步骤拆到 final 阶段——final 镜像通常精简无 gcc，根本跑不了 pecl install。正确做法是：
- builder 阶段用完整开发镜像（如
php:8.2-cli+ 编译工具），执行composer install和所有pecl install - final 阶段用最小运行镜像（如
php:8.2-cli-slim），但必须提前复制 builder 阶段的/usr/lib/php/extensions/*和/usr/local/etc/php/conf.d/*.ini - 最关键的是：两个阶段的基础镜像 PHP 版本、架构（x86_64/arm64）、ZTS/NTS 模式必须完全一致，否则扩展 so 文件无法加载
- 验证方式：在 builder 阶段末尾加
php -m | grep grpc；在 final 阶段启动后也执行同样命令，确认输出一致
很多人只复制 vendor/，却忘了复制扩展 so 文件和 ini 配置，结果容器跑起来就报 extension missing。
composer.lock 里平台约束（platform）必须匹配容器环境
composer.lock 顶部的 platform 字段如果锁死了 "php": "8.1.0"，而你 Docker 里用的是 php:8.2-cli，Composer 就可能拒绝安装某些需编译的包（尤其当它们声明了 ext-grpc: "^1.40" 这类平台依赖时）。
- 检查
composer.json是否有"config": {"platform": {"php": "8.2.0"}}，并确保它与实际镜像 PHP 版本一致 - 不要用
--ignore-platform-reqs绕过——它会让 Composer 跳过扩展可用性校验，导致构建成功但运行失败 - 若必须兼容多个 PHP 版本，应在
composer.json中明确列出所需扩展及其最低版本，例如："ext-grpc": "^1.45"
平台约束不是可选项，它是 Composer 判断“当前环境能否装这个包”的第一道门。门没开，后面所有编译动作都不会触发。
