hyperf项目docker镜像需双阶段构建：builder用php:8.2-cli编译swoole/swow，runner用php:8.2-cli-slim仅copy扩展文件与配置，严格分离依赖与运行环境。
Hyperf项目Docker镜像打包攻略
Hyperf项目打包成Docker镜像时，常因混入编译工具链、dev依赖和缓存导致镜像体积飙升至1.5GB以上，启动失败报Class swoole_http_server not found，根本原因在于构建阶段与运行阶段未分离。
第一步：创建双阶段Dockerfile，明确划分builder和runner阶段。builder阶段用php:8.2-cli（非Alpine），确保pecl install swoole能顺利编译；runner阶段必须用php:8.2-cli-slim——它只有65MB左右，不含apt、bash、man手册等冗余内容，且基于glibc，兼容性稳定。
第二步：在builder阶段安装Swoole扩展后，必须显式启用并验证路径。执行RUN docker-php-ext-enable swoole && ls /usr/local/lib/php/extensions/*/swoole.so，若无输出说明扩展未生成或路径异常，后续COPY会失效。
第三步：runner阶段只允许COPY --from=builder两处关键文件——【/usr/local/lib/php/extensions/*/swoole.so】和【/usr/local/etc/php/conf.d/docker-php-ext-swoole.ini】。漏掉任一，Hyperf启动即报错“Class swoole_http_server not found”。
第四步：应用代码复制时加--chown=www-data:www-data。执行COPY --chown=www-data:www-data . /var/www/html/，否则Hyperf因权限不足卡在启动初始化阶段，日志里不报错但进程不监听9501端口。
第五步：builder阶段末尾必须彻底清理缓存。RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*，否则Docker构建缓存机制可能将build-essential等包意外继承进runner层，哪怕没被COPY也会污染最终镜像。
Kimi AI优化Swow容器多阶段构建全流程
Swow是Hyperf生态中替代Swoole的新兴协程引擎，但官方未提供预编译二进制，必须源码编译。Kimi AI辅助优化的关键在于规避musl libc兼容陷阱，并压缩编译中间产物。
方法一：用builder阶段交叉编译Swow，避免在runner阶段装gcc。在builder中执行git clone https://github.com/swow/swow && cd swow && git checkout v1.4.3 && phpize && ./configure --enable-sockets && make -j$(nproc) && make install。这一步耗时但只发生一次。
方法二：runner阶段禁止任何apt或pecl操作。Swow.so必须由builder编译好后COPY过来，再RUN docker-php-ext-enable swow启用。若在runner里RUN pecl install swow，会触发Alpine下musl libc与PHP头文件ABI不匹配，容器启动直接panic。
方法三：精简Swow编译产物。builder阶段make install后，不要直接COPY整个extensions目录。改用COPY --from=builder /usr/local/lib/php/extensions/*/swow.so /usr/local/lib/php/extensions/，并手动创建conf.d/swow.ini，内容为extension=swow.so。这样可跳过swow的测试套件、文档和debug符号，节省12MB以上空间。
注意：Swow 1.4.3要求PHP 8.2+且开启sockets扩展，builder阶段务必先RUN docker-php-ext-install sockets，否则configure会失败。
