hyperf镜像体积过大主因是构建时混入编译工具链、dev依赖等冗余内容；多阶段构建+php:8.2-slim基础镜像可将1.5gb降至约150mb，兼顾体积与musl libc兼容性风险。
Hyperf 镜像体积过大，根本原因不是框架本身，而是构建时把编译工具链、源码、dev依赖、缓存全塞进最终镜像里了。用多阶段构建 + Alpine 镜像能直接砍掉 80% 以上体积，但要注意 Alpine 不是万能解药——musl libc 兼容性问题会反向拖慢构建甚至引发运行时崩溃。
为什么 hyperf/hyperf:latest 镜像动辄 1.5GB？
官方镜像默认基于 php:8.2-cli（Debian），自带完整包管理器、调试工具、文档、man 手册等；再叠加 Swoole 编译过程产生的中间文件、composer install --no-dev 未清理的 vendor 缓存、以及未剥离的 .git 和测试目录，体积必然失控。
常见错误现象包括：
- 执行
docker images | grep hyperf显示镜像大小超过 1.2GB - CI 流水线中
docker build卡在RUN pecl install swoole步骤（Alpine 下需从源码编译） - 容器启动后
php -m | grep swoole返回空，扩展实际未启用
多阶段构建：分离 builder 与 runtime 的关键写法
必须拆成两个明确阶段：第一阶段装齐所有编译依赖，第二阶段只保留 PHP 运行时 + 编译好的扩展 + 应用代码。不能只靠 FROM hyperf/hyperf:alpine 一步到位——那只是换了个基础镜像，没解决“构建即污染”的本质问题。
实操要点：
- builder 阶段用
php:8.2-cli或php:8.2-cli-slim，确保glibc环境下可直接安装预编译的 Swoole wheel（如swoole-5.1.0） - runtime 阶段改用
php:8.2-alpine，但必须手动复制已编译好的swoole.so和extensions目录，不能指望pecl install在 Alpine 里成功 - 务必用
COPY --from=builder显式指定路径，例如：COPY --from=builder /usr/local/lib/php/extensions/no-debug-non-zts-20220829/swoole.so /usr/local/lib/php/extensions/no-debug-non-zts-20220829/ - 最后在 runtime 阶段执行
docker-php-ext-enable swoole，否则扩展不会加载
Alpine 镜像的坑：musl libc 导致的兼容性断裂
Hyperf 官方文档推荐 php:8.1-cli-alpine，但实际项目中大量第三方扩展（如 redis、protobuf、grpc）在 Alpine 上无法使用预编译二进制，必须走源码编译，这会触发以下连锁问题：
-
pecl install redis失败，报错configure: error: C compiler cannot create executables（缺gcc、g++等构建工具） - 强行安装
build-base后，编译出的扩展可能因 musl 和 glibc ABI 差异，在运行时 panic 或 segfault - 即使编译成功，镜像体积反而比
-slim版本更大——因为同时打包了gcc+g+++make+ 扩展源码
更稳妥的选择是：builder 阶段用 php:8.2-slim（glibc + 轻量），runtime 阶段也用 php:8.2-slim，而非 Alpine。体积仍可压到 150MB 左右，且无兼容性风险。
最后检查点：别让 .dockerignore 成摆设
即便用了多阶段构建，如果 .dockerignore 里没排除这些内容，它们仍会被 COPY 进 builder 阶段，间接增大中间镜像体积，拖慢整个构建流程：
-
node_modules/（Hyperf 项目一般不用，但误加了就白占空间） -
vendor/.git/（Composer 安装后残留的 Git 元数据） -
tests/、docs/、.env.example -
composer.lock必须保留，但composer.json中的require-dev已被--no-dev过滤，无需额外处理
真正起效的 .dockerignore 至少应包含：.git、.gitignore、tests、docs、node_modules、vendor/.git。
多阶段构建不是魔法开关，它只负责“剪枝”，而 builder 阶段是否干净、runtime 阶段是否真轻量、.dockerignore 是否生效，三者缺一不可。Alpine 更适合 Go/Rust 类静态编译语言，PHP 生态里，-slim + 多阶段才是稳态解。
