最近在整理 PHP 项目的交付流程时我又一次被客户的服务器环境折磨到怀疑人生有的机器只有老掉牙的 PHP 5.6有的压根没装 PHP还有的装了 PHP 但是缺扩展。每一个客户的环境都不一样每一条部署文档都要单独写。我忍不住想如果 PHP 能像 Go 一样编译完直接丢一个原生二进制文件过去就能跑那该多省事。于是我开始折腾“用 Docker 一键编译出零环境依赖的 PHP 原生二进制”这套方案折腾了几天踩了无数坑终于把流程跑通了。这篇文章就是完整的实操记录。这套方案的核心是把 PHP 解释器、扩展、第三方依赖库全部静态链接进同一个 ELF 可执行文件最终交付物只有一个文件或带少量配置文件的目录目标服务器上不需要预装 PHP不需要装扩展甚至不需要匹配发行版。它适合两类人一类是被 PHP 环境部署反复折腾的应用开发者另一类是嫌 Docker 镜像分发太笨重、想要更接近 Go 式分发体验的运维工程师。1. 为什么是“一个二进制”Go 分发体验与 PHP 困境1.1 Go 的分发模型到底赢在哪用过 Go 的人都有种共同体验写完代码设置好CGO_ENABLED0执行GOOSlinux GOARCHamd64 go build产物就是一个带执行权限的文件。这个文件自带运行时、自带依赖、自带调度器网络请求、JSON 解析、模板渲染全都包含在单个文件内部。把它用 scp 扔到任何一台干净 Linux 服务器上chmod x后直接./app就能跑不需要先装 Go 语言环境不需要安装任何系统依赖更不用纠结系统里有没有某个动态库。更爽的是交叉编译。我在 Mac 上开发一条命令就能生成 Linux 版、ARM 版、Windows 版。目标机器越干净这件事的优势反而越明显。客户内网服务器往往不连外网你要在那上面装 PHP 和扩展光是解决 yum/apt 源的问题就能耗掉半天。而 Go 程序的运维脚本只需要一句“把文件传上去加执行权限运行”没有中间商赚差价。1.2 PHP 传统分发的几重尴尬PHP 的分发体验跟 Go 完全不是一个画风。最常见的是把源码或者 Dockerfile 交给客户然后开始无尽的环境适配系统自带的 PHP 版本跟项目要求的版本对不上改 yum 源、加 ppa、自己编译每一步都可能踩坑。扩展是独立.so文件版本、API 编号、依赖库稍有偏差就加载失败。不同发行版对 PHP 的目录结构、配置路径、扩展扫描目录约定都不一样。客户机器上还经常并行跑着其他 PHP 应用改一个全局配置可能把别的项目搞挂。即便用 Docker 镜像分发虽然能解决环境一致性问题但客户侧需要安装 Docker、需要拉镜像或导入镜像包、需要理解容器和宿主机的目录挂载关系。对于使用者来说“我只要一个能跑的程序”才是最朴素的需求。1.3 这里说的“零环境依赖”到底指什么我说的零环境依赖不是指代码不依赖任何库而是指目标机器上不需要预装 PHP 运行时不需要单独安装扩展也不需要处理 PHP 版本冲突。编译产物是一个原生 ELF 可执行文件PHP 解释器本体、Zend 引擎、扩展、libc 相关能力都被静态打包到了一起。我刚开始也觉得这是天方夜谭毕竟 PHP 是解释型动态语言扩展机制天然倾向于动态加载。但换个角度想PHP 的解释器是用 C 写的C 语言能静态链接PHP 理论上就能静态编译。实际做完之后交付体验确实非常接近 Go编译产物复制到目标机器直接运行依赖的只是一套可预测的 Linux 内核 ABI而不是特定发行版上的 PHP 软件包。不过有一说一“零环境依赖”并不等于“单个文件走天下”。HTTPS 证书、php.ini 配置这类东西目前还没法完全塞进二进制里这一点我在后面的踩坑部分会专门展开。2. 静态编译背后的硬骨头glibc、dlopen 与 PHP SAPI2.1 给 PHP 加个-static就完事了吗很多人包括一开始的我以为静态编译就是把gcc的命令换成带-static或者给 configure 加个参数就完事了。真去试了才发现这条路远没有想象中平坦。PHP 本身是用 C 写的没错但它不是一个孤零零的可执行程序。编译过程中要链接 openssl、libxml2、libcurl、zlib、sqlite、oniguruma 这些第三方库。普通发行的 PHP 二进制对这些库都是动态链接的libphp运行时会调用dlopen()加载扩展。要让最终的 php 二进制“搬到哪里都能跑”所有这些问题都得逐一解决。2.2 glibc 静态编译的著名深坑先说说 C 标准库的选择。当时我第一反应是直接在 Ubuntu 里用 glibc 静态编译试过之后发现麻烦不断。glibc 的静态链接在解析/etc/nsswitch.conf时有个老毛病NSSName Service Switch模块机制把用户解析、组解析、域名解析都做成了运行时动态加载的模块。静态链接时nss_files、nss_dns这些模块被排除在二进制之外一旦 PHP 代码里调用getpwnam()、posix_getpwuid()、getaddrinfo()之类轻则返回异常结果重则直接让 FPM 起不来。Alpine Linux 默认用的 musl libc 就没有这些历史包袱。musl 的实现更精简静态链接行为干净利落直接读/etc/passwd、/etc/resolv.conf这类文件不走复杂模块化分发。所以“用 Docker 静态编译原生二进制”这个场景里我最终选择了 Alpine 作为构建环境工具链用musl-gcc这也和当前容器生态里“静态链接去 Alpine 化”的普遍实践对上了。2.3 PHP 的扩展加载机制决定了静态化不是普通 C 项目PHP 扩展在默认情况下是运行期动态加载的。php.ini里写一行extensionredis.soPHP 启动时就去扩展目录找这个.so找到后用dlopen()把符号灌进来。这在传统部署里很灵活但在静态二进制里就是麻烦。静态二进制里没有运行期的动态链接器也没法在后端新建一个.so加载进来。所以扩展必须在编译期间完成“注册”把扩展里的函数符号表、类符号表全部融进 PHP 内核的静态符号表。这意味着我们要在 configure 阶段就把扩展一次性选齐并且用--enable-xxxstatic这种形式把它们链入主程序。之前习惯的“缺啥扩展后期装上”的玩法彻底行不通了。2.4 为什么绕不开 PHP 的 SAPI 概念PHP 在不同的运行方式下对应不同的 SAPIServer API命令行下是 CLI SAPI跑 FPM 是 FPM SAPI嵌入到别的 C 程序是 Embed SAPI。做静态编译时我最关心的是 CLI SAPI 和 FPM SAPI还有一个容易被忽略的 Embed SAPI。Embed SAPI 的本质是把 PHP 引擎当作一个 C 库编译产物是libphp.a。很多静态编译方案绕不开它因为 PHP 内核和扩展的符号都需要以库的形式链接进最终的可执行文件。后面要讲到的--enable-embedstatic就是干这个事的。对大多数人来说不用把它理解得太深只要记住PHP 静态编译的关键不是单给解释器加个静态标志而是让整个扩展生态与运行环境在编译期闭环。3. Docker 构建流水线从镜像到原生二进制的完整链路3.1 为什么要用 Docker 当“编译器”这里有个看起来很反直觉的点最终产物是原生二进制不需要 Docker但编译过程我强烈建议放在 Docker 里做。第一个理由是可复现性。我在自己的 Mac 上编译跟朋友在 Ubuntu 上编译工具链版本、autoconf 参数、依赖库路径都不一样结果可能一个成功一个失败。而 Dockerfile 把整套构建环境固定成了一份代码什么时候构建、在哪台机器构建结果都是一样的。第二个理由是交叉编译能力。现代 Docker 的 buildx 支持多平台构建可以在 x86 的机器上通过 QEMU 模拟出 ARM 的构建环境直接产出linux/arm64的静态 PHP。这对要给树莓派或者国产 ARM 服务器交付的场景特别有用不需要真的买一台 ARM 机器来干活。第三个理由是不污染宿主环境。如果直接在服务器上装一堆编译工具链、下载各种源码、执行 make install很容易把服务器搞乱。Docker 容器用完即弃宿主干干净净这才是工程化应该有的样子。3.2 一个可用的构建 Dockerfile 骨架下面这个 Dockerfile 是我在 PHP 8.3 Alpine 3.20 上验证过的版本核心思路是“构建阶段和输出阶段彻底分开”。# 构建阶段 FROM alpine:3.20 AS build # 编译工具链和基础依赖 RUN apk add --no-cache \ build-base \ autoconf \ automake \ libtool \ pkgconfig \ wget \ xz \ git \ linux-headers \ ca-certificates \ openssl-dev \ zlib-dev \ libxml2-dev \ libcurl \ curl-dev \ oniguruma-dev \ sqlite-dev \ libzip-dev \ php83 \ php83-common \ php83-cli # 创建工作目录 WORKDIR /opt/build # 下载 PHP 源码包 ARG PHP_VERSION8.3.12 RUN wget -q https://www.php.net/distributions/php-${PHP_VERSION}.tar.xz \ tar -xf php-${PHP_VERSION}.tar.xz \ mv php-${PHP_VERSION} php-src cd php-src # 把构建脚本复制进容器 COPY build-php.sh /opt/build/build-php.sh RUN chmod x /opt/build/build-php.sh # 执行构建 RUN /opt/build/build-php.sh # 验证阶段 FROM alpine:3.20 AS verify COPY --frombuild /opt/build/php-src/sapi/cli/php /usr/local/bin/php RUN php -v \ php -m \ ldd /usr/local/bin/php || true # 输出阶段导出二进制 FROM scratch AS artifact COPY --frombuild /opt/build/php-src/sapi/cli/php /php这里有一个很关键的设计最后阶段的FROM scratch不是用来跑程序的它是为了让docker buildx能通过--output typelocal把二进制直接导出到宿主机。构建完只需要在宿主机上执行docker buildx build --platform linux/amd64,linux/arm64 -o out .你会发现out/linux_amd64/php和out/linux_arm64/php两个原生二进制文件就出现在当前目录了。这种方式和 Go 交叉编译下载产物几乎是一个体验。3.3 为什么验证阶段要用 Alpine 而不是 scratch你可能注意到我在构建阶段后面加了一个基于 Alpine 的 verify 阶段。这一步非常必要把编译出来的 PHP 复制到一个全新的 Alpine 容器里跑一遍php -v和php -m确认它能正常工作。如果直接 COPY 到scratch一旦缺少证书文件或者配置路径不对报错会非常让人头大。Alpine 里还自带了一个可用的/etc/ssl/certs/ca-certificates.crt对验证 HTTPS 功能很有帮助。等这一阶段跑通了再导到宿主机上才能放心地扔到客户环境。4. 一键编译脚本拆解关键参数、构建顺序与多平台导出4.1 核心构建脚本 build-php.sh 逐段说明构建流程的全部秘密都在这份脚本里。这里我把脚本拆开逐段解释这样你改起来心里有底。#!/bin/sh set -ex export CFLAGS-static -O2 export LDFLAGS-static cd /opt/build/php-src ./configure \ --prefix/usr/local/php \ --enable-cli \ --enable-static \ --disable-shared \ --enable-embedstatic \ --with-config-file-scan-dir/etc/php/conf.d \ --with-openssl \ --enable-openssl \ --enable-mysqlnd \ --with-mysqlimysqlnd \ --with-pdo-mysqlmysqlnd \ --with-sqlite3 \ --with-pdo-sqlite \ --enable-mbstring \ --enable-bcmath \ --enable-zip \ --with-zlib \ --with-curl \ --disable-cgi \ --disable-phpdbg \ --without-pear参数里面水分不少逐个过一遍--enable-static --disable-shared这是静态编译的基础开关让构建系统尽量生成静态链接的产物而不是.so动态库。--enable-embedstatic把 PHP 引擎编译成静态库embed SAPI后续链接 CLI 可执行文件时会用到。没有这个很多与扩展相关的静态符号不会被拉进主程序。--enable-cli确保生成sapi/cli/php这个可执行文件而不是只输出库文件。--with-openssl --enable-opensslPHP 8 里 openssl 已经是独立扩展了必须显式启用否则openssl_encrypt、HTTPS 流封装全都不存在。--enable-mysqlnd --with-mysqlimysqlnd --with-pdo-mysqlmysqlndMySQL 客户端库直接用 PHP 自带的 mysqlnd这个很关键。mysqlnd 是 PHP 官方内置的 MySQL 驱动不需要单独链接第三方 C 库对静态编译友好得多顺便避开了libmysqlclient那一堆动态库依赖。--with-curlcurl 扩展依赖 libcurl。在 Alpine 里配置好curl-dev后静态编译时它会链接到静态版本的 curl 库。--with-config-file-scan-dir/etc/php/conf.d这个参数决定了 PHP 启动时扫描哪个目录作为额外的配置文件目录。静态二进制打包后不会有传统 PHP 安装路径里的php.ini所以预定义一个扫描目录部署时把自定义 ini 文件放进去即可非常灵活。--without-pear不需要 PEAR 工具链少编一堆无关的东西减小体积。--disable-cgi --disable-phpdbg只留 CLI不要冗余入口。configure 之后是编译环节make -j$(nproc)-j$(nproc)是用满所有 CPU 核心。PHP 静态编译耗时不短我在 8 核机器上跑一次大约 5 到 10 分钟。构建脚本最后需要把产物集中到一个固定位置mkdir -p /opt/export cp sapi/cli/php /opt/export/php strip /opt/export/phpstrip是必须的一步它能去掉二进制里的调试符号体积能从 80MB 左右降到 30MB 左右。真正生产交付时这体积虽然比 Go 程序大得多但换来的是一个完整的 PHP 运行时值了。4.2 依赖库的静态链接处理方式在 Alpine 里通过apk add openssl-dev这类包安装的开发库通常已经附带了静态.a文件。PHP 的 configure 在检测库时会优先链接.so但在我们强制LDFLAGS-static的环境下链接器会倾向找.a文件。这里有个坑有些 Alpine 包虽然带了.a但如果你还想让 openssl 和 curl 再静一层嵌套curl 依赖 openssl链接顺序可能会出问题。处理方法是给 configure 加上export PKG_CONFIG_PATH/usr/lib/pkgconfig export CPPFLAGS-I/usr/include如果你发现某些库静态链接后依然报“找不到-lcrypto”之类的错误多半是库的链接顺序问题。此时可以把LDFLAGS改成export LDFLAGS-static -lcrypto -lssl -lz -lcurl但更推荐的做法是回 Alpine 确认 openssl-dev 装好了因为手动指定库顺序在 PHP 这种超大型 configure 体系里很容易引入新问题。4.3 buildx 多平台导出的细节在 Dockerfile 构建成功之后docker buildx build是发布产物的最后一步。这里有一个容易被忽略的点如果你的 Docker 版本较新buildx 是内置的如果是老版本需要先启用实验特性或者单独安装插件。命令中的平台参数docker buildx build --platform linux/amd64,linux/arm64 -o out .-o out会把每个平台的产物写到out/目录下面目录结构类似out/ ├── linux_amd64/php └── linux_arm64/php这样一份构建命令同时产出两种架构跟 Go 的GOARCHamd64/GOARCHarm64交叉编译形成了完美对应。以后给客户交付时问清楚对方的 CPU 架构直接把对应文件发过去就行。5. 验证零依赖与踩坑记录别让“静态”两个字骗了你5.1 验证步骤不能说“我觉得是静态的”静态编译完成后我习惯做一套固定验证流程缺一不可验证目标命令预期结果检查文件类型file php输出中包含statically linked检查动态库依赖ldd php提示not a dynamic executable在纯净容器中运行docker run --rm -v $PWD/php:/php alpine:latest /php -v正常输出 PHP 版本号测试扩展加载数量php -m能看到编译时启用的扩展列表且不会出现unable to load字样ldd是最快的一招看到not a dynamic executable时心里就踏实一大半。但这份踏实后面还暗藏着几个坑我在实际跑通后接二连三踩了个遍。5.2 坑一HTTPS 请求报证书错误第一次在客户机器上运行编译好的二进制一调用file_get_contents(https://api.example.com)就报错SSL operation failed with code 1. OpenSSL Error messages: error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed。原因很简单静态二进制把 openssl 库编译进去了但是系统 CA 根证书文件是独立于二进制存在的。目标机器上如果没装ca-certificates包目录里没有/etc/ssl/certs/ca-certificates.crtSSL 验证就过不了。解决办法是配置openssl.cafile在编译时就指定一个固定的证书文件路径。更好的做法是把证书文件作为部署包的一部分带上比如放在/etc/php/conf.d/旁边然后在php.ini里写openssl.cafile/etc/ssl/certs/ca-certificates.crt我把 CA 证书跟 php 二进制一起交付客户那儿不存在服务器上部署时放到指定路径就行。这个妥协不影响“零环境依赖”的核心价值——我们仍然不依赖对方的 PHP 环境只是依赖一个公共 CA 证书文件。5.3 坑二php.ini 路径与扩展配置静态二进制的 PHP 不会自动去读/usr/local/lib/php.ini或者/etc/php.ini因为源码编译时没有走make install传统安装路径根本没建立。解决思路就是前面提到的--with-config-file-scan-dir/etc/php/conf.d。编译时写死扫描目录以后部署时只需要保证目标机器上存在/etc/php/conf.d/然后把配置丢进去。比如我可以放一个; /etc/php/conf.d/upload.ini upload_max_filesize 64M post_max_size 64M memory_limit 256MPHP 启动时自动扫描这个目录所有 ini 文件都会被加载。这样既保持了二进制的可移植性又保留了配置灵活性。5.4 坑三UPX 压缩后二进制直接崩静态二进制的体积在一二十到七八十 MB 之间随着扩展增多会继续膨胀。我起初想用 UPX 给 PHP 二进制做一层压缩期望能从 45MB 压到 18MB 左右。结果压缩后的二进制在部分内核版本上运行时直接 Segmentation Fault。原因大家讨论得比较多大致是 UPX 解压时动态构造内存页的方式和 musl 静态二进制存在兼容性隐患。所以现在我的经验是不要对 PHP 静态二进制做 UPX 压缩老老实实strip就够了。体积大就大一点稳定性第一。5.5 坑四FPM 模式下的用户解析如果你编译了--enable-fpm那么静态 php-fpm 二进制在启动时如果配置user www-data而目标机器的/etc/passwd里没有这个用户就会直接启动失败或退出。传统 PHP 安装包通常会创建www-data用户但静态二进制不会干这种事。处理方式要么在部署脚本里预先创建用户要么 FPM 配置里直接用user nobody。nobody 用户几乎在所有 Linux 系统上存在做隔离足够用。这一点在写部署文档时务必提醒客户不然对方拿到二进制之后容易卡在这一步以为是二进制坏了。5.6 坑五ext-posix 之类的“编译期 vs 运行期”差异静态二进制一旦编译完成功能集合就固定了。运行期的dl()函数形同虚设因为你没法在系统里放任意.so扩展。以前那种“临时装一个 redis.so改一下 php.ini重启 FPM”的应急手段在静态二进制里不存在。这既是约束也是优势。约束在于你必须提前想清楚项目需要哪些扩展优势在于任何人拿到这个二进制运行行为都跟你测试时完全一致不会因为目标机器上的某个扩展版本不一致导致诡异死机。6. 进阶外部扩展redis / apcu静态编译的正确姿势6.1 内置扩展和外部扩展的编译差异PHP 源码树的ext/目录里自带很多官方扩展比如 mbstring、mysqlnd、openssl、sqlite、bcmath、zip。这些扩展的静态编译只需要在 configure 时加上--enable-xxx或--with-xxx构建系统会直接把它们纳入内核符号表非常省事。但实际项目里往往还需要 PECL 仓库的外部扩展比如redis、apcu、imagick、swoole。这些扩展不在 PHP 源码树里需要先pecl download或 git clone 拿到源码再通过phpize生成自己的 configure 脚本然后单独编译。编译出来的默认产物是.so如果想把它们融进静态二进制需要让它们生成静态.a并注册进 PHP 内核。这个流程比内置扩展复杂一个量级因为 PHP 的构建系统在生成最终链接命令时不会自动发现这些外部扩展的符号。6.2 手写外部扩展静态链接的通用套路以 redis 扩展为例手写的大致思路是先把扩展源码编译成静态库pecl download redis cd redis-6.0.2 # 使用构建环境里的 phpize 生成 configure phpize ./configure --with-php-config/usr/local/php/bin/php-config --enable-redisstatic make执行完以后modules/目录下会生成redis.a和redis.so。redis.a是我们要的静态库。接下来要把这个静态库加入 PHP 最终链接阶段。做法是在 PHP 源码树的configure配置里通过EXTENSION_LIBS和CFLAGS把它带进去。一般的做法是修改或生成一个config.nice文件把--enable-redisstatic和--with-php-config...都加进最终 configure 命令同时让 PHP 构建系统知道这个扩展的源文件和动态库路径。这里有一句非常值得写给后来者的话手写这套流程极其容易受 PHP 小版本和扩展版本的影响经常出现编译通过、链接失败或者链接成功、运行时符号找不到的情况。我不是劝退你研究底层而是提醒你如果目标是尽快上线可以直接借助现成封装。6.3 省心路线static-php-cli 这类工具已经替你踩完坑有一个开源项目叫static-php-cliGitHub 上搜 crazywhalecc/static-php-cli 就能找到它本质上把整套 PHP 静态编译和外部扩展静态链接的流程做了产品化封装。它不仅支持 redis、apcu、swoole还支持 imagick、pcntl、event 等一堆常用扩展并且自动处理依赖库的静态编译顺序。使用极其简单拉下来以后直接执行它的构建命令指定 PHP 版本、扩展列表、目标架构它会把 openssl、curl、sqlite、redis 等依赖全部编排好最后在dist/目录下生成你想要的静态二进制。我在自己的生产交付方案里是这样分工的团队自研的 PHP 版本管理和核心扩展配置我仍然自己控制但外部扩展的静态链接我直接交给 static-php-cli。这样既保住了对构建过程的掌控力又节省了大量调试时间。另外还要点名 FrankenPHP它是 Caddy 作者主导的“PHP 应用服务器”项目把 Caddy、PHP、静态链路整合成一个可执行文件。如果你要分发的是现代 PHP Web 应用可以进一步了解这个方案它比单纯的 CLI 二进制更贴近实际生产。6.4 我个人的倾向与取舍折腾到这里我给自己的项目定了一条原则要功能完整、扩展丰富、长期维护选 static-php-cli要深刻理解原理、完全掌控产物就亲自手搓一遍 configure 脚本。两种路线没有高下之分取决于你用这套方案的频率和深度。如果一年只做一两次交付没必要从零造轮子如果你是准备把它变成团队的基础设施那必须吃透每个参数的含义。我最初是自己手搓因为我对 PHP 内核链接机制好奇踩完 Redis 扩展的坑之后我反而理解了为什么社区会有 static-php-cli 这种工具存在。使用别人的工具不可耻可耻的是把工具当成黑盒却不去理解背后的约束导致上了生产之后手足无措。7. 这套方案在我项目里的实际躺平效果我把这套“Docker 一键编译静态 PHP”的流程接入 CI 之后客户交付从一项“技术活”变成了“体力活”。每次发新版本流水线自动构建出linux/amd64和linux/arm64两个原生二进制我把产物传到网盘或者直接 scp 给客户的服务器再附带一份不到 20 行的部署说明放二进制、放配置目录、创建 nobody 用户、写 systemd 单元文件完事。过去那种“客户说 PHP 报错我远程上去一看发现是扩展缺失”的噩梦基本消失了。因为二进制是自包含的行为在每台机器上都一样。客户甚至不太关心你有没有 PHP他们只关心这个程序能不能跑而这恰恰是 Go 式分发的精髓。也有一个不得不提醒的地方PHP 静态二进制的体积确实比 Go 大得多一般会在 30MB 到 80MB 之间配置和证书也必须通过conf.d目录和指定路径注入。所以它更适合“交付固定应用”而不是“交付一套通用 PHP 环境”。如果客户需要一套通用的 PHP 运行环境继续用容器或者传统安装包反而更合适。我对这套流程最直观的体会是技术选型没有银弹但“把环境装进产物”的思路在各个语言里都值得复制。Go 把一个运行时塞进一个文件PHP 也可以把解释器、扩展、依赖塞进一个文件。你只需要在构建期多想一步部署期的烦恼就能少一多半。最后留一个小建议找一台干净测试机先把php -v的静态二进制跑通再上php -S 0.0.0.0:8080跑一个简单 Web 应用最后再考虑 FPM、redis 这些进阶模块。一步步来踩坑的代价会小很多。
最近在整理 PHP 项目的交付流程时我又一次被客户的服务器环境折磨到怀疑人生有的机器只有老掉牙的 PHP 5.6有的压根没装 PHP还有的装了 PHP 但是缺扩展。每一个客户的环境都不一样每一条部署文档都要单独写。我忍不住想如果 PHP 能像 Go 一样编译完直接丢一个原生二进制文件过去就能跑那该多省事。于是我开始折腾“用 Docker 一键编译出零环境依赖的 PHP 原生二进制”这套方案折腾了几天踩了无数坑终于把流程跑通了。这篇文章就是完整的实操记录。这套方案的核心是把 PHP 解释器、扩展、第三方依赖库全部静态链接进同一个 ELF 可执行文件最终交付物只有一个文件或带少量配置文件的目录目标服务器上不需要预装 PHP不需要装扩展甚至不需要匹配发行版。它适合两类人一类是被 PHP 环境部署反复折腾的应用开发者另一类是嫌 Docker 镜像分发太笨重、想要更接近 Go 式分发体验的运维工程师。1. 为什么是“一个二进制”Go 分发体验与 PHP 困境1.1 Go 的分发模型到底赢在哪用过 Go 的人都有种共同体验写完代码设置好CGO_ENABLED0执行GOOSlinux GOARCHamd64 go build产物就是一个带执行权限的文件。这个文件自带运行时、自带依赖、自带调度器网络请求、JSON 解析、模板渲染全都包含在单个文件内部。把它用 scp 扔到任何一台干净 Linux 服务器上chmod x后直接./app就能跑不需要先装 Go 语言环境不需要安装任何系统依赖更不用纠结系统里有没有某个动态库。更爽的是交叉编译。我在 Mac 上开发一条命令就能生成 Linux 版、ARM 版、Windows 版。目标机器越干净这件事的优势反而越明显。客户内网服务器往往不连外网你要在那上面装 PHP 和扩展光是解决 yum/apt 源的问题就能耗掉半天。而 Go 程序的运维脚本只需要一句“把文件传上去加执行权限运行”没有中间商赚差价。1.2 PHP 传统分发的几重尴尬PHP 的分发体验跟 Go 完全不是一个画风。最常见的是把源码或者 Dockerfile 交给客户然后开始无尽的环境适配系统自带的 PHP 版本跟项目要求的版本对不上改 yum 源、加 ppa、自己编译每一步都可能踩坑。扩展是独立.so文件版本、API 编号、依赖库稍有偏差就加载失败。不同发行版对 PHP 的目录结构、配置路径、扩展扫描目录约定都不一样。客户机器上还经常并行跑着其他 PHP 应用改一个全局配置可能把别的项目搞挂。即便用 Docker 镜像分发虽然能解决环境一致性问题但客户侧需要安装 Docker、需要拉镜像或导入镜像包、需要理解容器和宿主机的目录挂载关系。对于使用者来说“我只要一个能跑的程序”才是最朴素的需求。1.3 这里说的“零环境依赖”到底指什么我说的零环境依赖不是指代码不依赖任何库而是指目标机器上不需要预装 PHP 运行时不需要单独安装扩展也不需要处理 PHP 版本冲突。编译产物是一个原生 ELF 可执行文件PHP 解释器本体、Zend 引擎、扩展、libc 相关能力都被静态打包到了一起。我刚开始也觉得这是天方夜谭毕竟 PHP 是解释型动态语言扩展机制天然倾向于动态加载。但换个角度想PHP 的解释器是用 C 写的C 语言能静态链接PHP 理论上就能静态编译。实际做完之后交付体验确实非常接近 Go编译产物复制到目标机器直接运行依赖的只是一套可预测的 Linux 内核 ABI而不是特定发行版上的 PHP 软件包。不过有一说一“零环境依赖”并不等于“单个文件走天下”。HTTPS 证书、php.ini 配置这类东西目前还没法完全塞进二进制里这一点我在后面的踩坑部分会专门展开。2. 静态编译背后的硬骨头glibc、dlopen 与 PHP SAPI2.1 给 PHP 加个-static就完事了吗很多人包括一开始的我以为静态编译就是把gcc的命令换成带-static或者给 configure 加个参数就完事了。真去试了才发现这条路远没有想象中平坦。PHP 本身是用 C 写的没错但它不是一个孤零零的可执行程序。编译过程中要链接 openssl、libxml2、libcurl、zlib、sqlite、oniguruma 这些第三方库。普通发行的 PHP 二进制对这些库都是动态链接的libphp运行时会调用dlopen()加载扩展。要让最终的 php 二进制“搬到哪里都能跑”所有这些问题都得逐一解决。2.2 glibc 静态编译的著名深坑先说说 C 标准库的选择。当时我第一反应是直接在 Ubuntu 里用 glibc 静态编译试过之后发现麻烦不断。glibc 的静态链接在解析/etc/nsswitch.conf时有个老毛病NSSName Service Switch模块机制把用户解析、组解析、域名解析都做成了运行时动态加载的模块。静态链接时nss_files、nss_dns这些模块被排除在二进制之外一旦 PHP 代码里调用getpwnam()、posix_getpwuid()、getaddrinfo()之类轻则返回异常结果重则直接让 FPM 起不来。Alpine Linux 默认用的 musl libc 就没有这些历史包袱。musl 的实现更精简静态链接行为干净利落直接读/etc/passwd、/etc/resolv.conf这类文件不走复杂模块化分发。所以“用 Docker 静态编译原生二进制”这个场景里我最终选择了 Alpine 作为构建环境工具链用musl-gcc这也和当前容器生态里“静态链接去 Alpine 化”的普遍实践对上了。2.3 PHP 的扩展加载机制决定了静态化不是普通 C 项目PHP 扩展在默认情况下是运行期动态加载的。php.ini里写一行extensionredis.soPHP 启动时就去扩展目录找这个.so找到后用dlopen()把符号灌进来。这在传统部署里很灵活但在静态二进制里就是麻烦。静态二进制里没有运行期的动态链接器也没法在后端新建一个.so加载进来。所以扩展必须在编译期间完成“注册”把扩展里的函数符号表、类符号表全部融进 PHP 内核的静态符号表。这意味着我们要在 configure 阶段就把扩展一次性选齐并且用--enable-xxxstatic这种形式把它们链入主程序。之前习惯的“缺啥扩展后期装上”的玩法彻底行不通了。2.4 为什么绕不开 PHP 的 SAPI 概念PHP 在不同的运行方式下对应不同的 SAPIServer API命令行下是 CLI SAPI跑 FPM 是 FPM SAPI嵌入到别的 C 程序是 Embed SAPI。做静态编译时我最关心的是 CLI SAPI 和 FPM SAPI还有一个容易被忽略的 Embed SAPI。Embed SAPI 的本质是把 PHP 引擎当作一个 C 库编译产物是libphp.a。很多静态编译方案绕不开它因为 PHP 内核和扩展的符号都需要以库的形式链接进最终的可执行文件。后面要讲到的--enable-embedstatic就是干这个事的。对大多数人来说不用把它理解得太深只要记住PHP 静态编译的关键不是单给解释器加个静态标志而是让整个扩展生态与运行环境在编译期闭环。3. Docker 构建流水线从镜像到原生二进制的完整链路3.1 为什么要用 Docker 当“编译器”这里有个看起来很反直觉的点最终产物是原生二进制不需要 Docker但编译过程我强烈建议放在 Docker 里做。第一个理由是可复现性。我在自己的 Mac 上编译跟朋友在 Ubuntu 上编译工具链版本、autoconf 参数、依赖库路径都不一样结果可能一个成功一个失败。而 Dockerfile 把整套构建环境固定成了一份代码什么时候构建、在哪台机器构建结果都是一样的。第二个理由是交叉编译能力。现代 Docker 的 buildx 支持多平台构建可以在 x86 的机器上通过 QEMU 模拟出 ARM 的构建环境直接产出linux/arm64的静态 PHP。这对要给树莓派或者国产 ARM 服务器交付的场景特别有用不需要真的买一台 ARM 机器来干活。第三个理由是不污染宿主环境。如果直接在服务器上装一堆编译工具链、下载各种源码、执行 make install很容易把服务器搞乱。Docker 容器用完即弃宿主干干净净这才是工程化应该有的样子。3.2 一个可用的构建 Dockerfile 骨架下面这个 Dockerfile 是我在 PHP 8.3 Alpine 3.20 上验证过的版本核心思路是“构建阶段和输出阶段彻底分开”。# 构建阶段 FROM alpine:3.20 AS build # 编译工具链和基础依赖 RUN apk add --no-cache \ build-base \ autoconf \ automake \ libtool \ pkgconfig \ wget \ xz \ git \ linux-headers \ ca-certificates \ openssl-dev \ zlib-dev \ libxml2-dev \ libcurl \ curl-dev \ oniguruma-dev \ sqlite-dev \ libzip-dev \ php83 \ php83-common \ php83-cli # 创建工作目录 WORKDIR /opt/build # 下载 PHP 源码包 ARG PHP_VERSION8.3.12 RUN wget -q https://www.php.net/distributions/php-${PHP_VERSION}.tar.xz \ tar -xf php-${PHP_VERSION}.tar.xz \ mv php-${PHP_VERSION} php-src cd php-src # 把构建脚本复制进容器 COPY build-php.sh /opt/build/build-php.sh RUN chmod x /opt/build/build-php.sh # 执行构建 RUN /opt/build/build-php.sh # 验证阶段 FROM alpine:3.20 AS verify COPY --frombuild /opt/build/php-src/sapi/cli/php /usr/local/bin/php RUN php -v \ php -m \ ldd /usr/local/bin/php || true # 输出阶段导出二进制 FROM scratch AS artifact COPY --frombuild /opt/build/php-src/sapi/cli/php /php这里有一个很关键的设计最后阶段的FROM scratch不是用来跑程序的它是为了让docker buildx能通过--output typelocal把二进制直接导出到宿主机。构建完只需要在宿主机上执行docker buildx build --platform linux/amd64,linux/arm64 -o out .你会发现out/linux_amd64/php和out/linux_arm64/php两个原生二进制文件就出现在当前目录了。这种方式和 Go 交叉编译下载产物几乎是一个体验。3.3 为什么验证阶段要用 Alpine 而不是 scratch你可能注意到我在构建阶段后面加了一个基于 Alpine 的 verify 阶段。这一步非常必要把编译出来的 PHP 复制到一个全新的 Alpine 容器里跑一遍php -v和php -m确认它能正常工作。如果直接 COPY 到scratch一旦缺少证书文件或者配置路径不对报错会非常让人头大。Alpine 里还自带了一个可用的/etc/ssl/certs/ca-certificates.crt对验证 HTTPS 功能很有帮助。等这一阶段跑通了再导到宿主机上才能放心地扔到客户环境。4. 一键编译脚本拆解关键参数、构建顺序与多平台导出4.1 核心构建脚本 build-php.sh 逐段说明构建流程的全部秘密都在这份脚本里。这里我把脚本拆开逐段解释这样你改起来心里有底。#!/bin/sh set -ex export CFLAGS-static -O2 export LDFLAGS-static cd /opt/build/php-src ./configure \ --prefix/usr/local/php \ --enable-cli \ --enable-static \ --disable-shared \ --enable-embedstatic \ --with-config-file-scan-dir/etc/php/conf.d \ --with-openssl \ --enable-openssl \ --enable-mysqlnd \ --with-mysqlimysqlnd \ --with-pdo-mysqlmysqlnd \ --with-sqlite3 \ --with-pdo-sqlite \ --enable-mbstring \ --enable-bcmath \ --enable-zip \ --with-zlib \ --with-curl \ --disable-cgi \ --disable-phpdbg \ --without-pear参数里面水分不少逐个过一遍--enable-static --disable-shared这是静态编译的基础开关让构建系统尽量生成静态链接的产物而不是.so动态库。--enable-embedstatic把 PHP 引擎编译成静态库embed SAPI后续链接 CLI 可执行文件时会用到。没有这个很多与扩展相关的静态符号不会被拉进主程序。--enable-cli确保生成sapi/cli/php这个可执行文件而不是只输出库文件。--with-openssl --enable-opensslPHP 8 里 openssl 已经是独立扩展了必须显式启用否则openssl_encrypt、HTTPS 流封装全都不存在。--enable-mysqlnd --with-mysqlimysqlnd --with-pdo-mysqlmysqlndMySQL 客户端库直接用 PHP 自带的 mysqlnd这个很关键。mysqlnd 是 PHP 官方内置的 MySQL 驱动不需要单独链接第三方 C 库对静态编译友好得多顺便避开了libmysqlclient那一堆动态库依赖。--with-curlcurl 扩展依赖 libcurl。在 Alpine 里配置好curl-dev后静态编译时它会链接到静态版本的 curl 库。--with-config-file-scan-dir/etc/php/conf.d这个参数决定了 PHP 启动时扫描哪个目录作为额外的配置文件目录。静态二进制打包后不会有传统 PHP 安装路径里的php.ini所以预定义一个扫描目录部署时把自定义 ini 文件放进去即可非常灵活。--without-pear不需要 PEAR 工具链少编一堆无关的东西减小体积。--disable-cgi --disable-phpdbg只留 CLI不要冗余入口。configure 之后是编译环节make -j$(nproc)-j$(nproc)是用满所有 CPU 核心。PHP 静态编译耗时不短我在 8 核机器上跑一次大约 5 到 10 分钟。构建脚本最后需要把产物集中到一个固定位置mkdir -p /opt/export cp sapi/cli/php /opt/export/php strip /opt/export/phpstrip是必须的一步它能去掉二进制里的调试符号体积能从 80MB 左右降到 30MB 左右。真正生产交付时这体积虽然比 Go 程序大得多但换来的是一个完整的 PHP 运行时值了。4.2 依赖库的静态链接处理方式在 Alpine 里通过apk add openssl-dev这类包安装的开发库通常已经附带了静态.a文件。PHP 的 configure 在检测库时会优先链接.so但在我们强制LDFLAGS-static的环境下链接器会倾向找.a文件。这里有个坑有些 Alpine 包虽然带了.a但如果你还想让 openssl 和 curl 再静一层嵌套curl 依赖 openssl链接顺序可能会出问题。处理方法是给 configure 加上export PKG_CONFIG_PATH/usr/lib/pkgconfig export CPPFLAGS-I/usr/include如果你发现某些库静态链接后依然报“找不到-lcrypto”之类的错误多半是库的链接顺序问题。此时可以把LDFLAGS改成export LDFLAGS-static -lcrypto -lssl -lz -lcurl但更推荐的做法是回 Alpine 确认 openssl-dev 装好了因为手动指定库顺序在 PHP 这种超大型 configure 体系里很容易引入新问题。4.3 buildx 多平台导出的细节在 Dockerfile 构建成功之后docker buildx build是发布产物的最后一步。这里有一个容易被忽略的点如果你的 Docker 版本较新buildx 是内置的如果是老版本需要先启用实验特性或者单独安装插件。命令中的平台参数docker buildx build --platform linux/amd64,linux/arm64 -o out .-o out会把每个平台的产物写到out/目录下面目录结构类似out/ ├── linux_amd64/php └── linux_arm64/php这样一份构建命令同时产出两种架构跟 Go 的GOARCHamd64/GOARCHarm64交叉编译形成了完美对应。以后给客户交付时问清楚对方的 CPU 架构直接把对应文件发过去就行。5. 验证零依赖与踩坑记录别让“静态”两个字骗了你5.1 验证步骤不能说“我觉得是静态的”静态编译完成后我习惯做一套固定验证流程缺一不可验证目标命令预期结果检查文件类型file php输出中包含statically linked检查动态库依赖ldd php提示not a dynamic executable在纯净容器中运行docker run --rm -v $PWD/php:/php alpine:latest /php -v正常输出 PHP 版本号测试扩展加载数量php -m能看到编译时启用的扩展列表且不会出现unable to load字样ldd是最快的一招看到not a dynamic executable时心里就踏实一大半。但这份踏实后面还暗藏着几个坑我在实际跑通后接二连三踩了个遍。5.2 坑一HTTPS 请求报证书错误第一次在客户机器上运行编译好的二进制一调用file_get_contents(https://api.example.com)就报错SSL operation failed with code 1. OpenSSL Error messages: error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed。原因很简单静态二进制把 openssl 库编译进去了但是系统 CA 根证书文件是独立于二进制存在的。目标机器上如果没装ca-certificates包目录里没有/etc/ssl/certs/ca-certificates.crtSSL 验证就过不了。解决办法是配置openssl.cafile在编译时就指定一个固定的证书文件路径。更好的做法是把证书文件作为部署包的一部分带上比如放在/etc/php/conf.d/旁边然后在php.ini里写openssl.cafile/etc/ssl/certs/ca-certificates.crt我把 CA 证书跟 php 二进制一起交付客户那儿不存在服务器上部署时放到指定路径就行。这个妥协不影响“零环境依赖”的核心价值——我们仍然不依赖对方的 PHP 环境只是依赖一个公共 CA 证书文件。5.3 坑二php.ini 路径与扩展配置静态二进制的 PHP 不会自动去读/usr/local/lib/php.ini或者/etc/php.ini因为源码编译时没有走make install传统安装路径根本没建立。解决思路就是前面提到的--with-config-file-scan-dir/etc/php/conf.d。编译时写死扫描目录以后部署时只需要保证目标机器上存在/etc/php/conf.d/然后把配置丢进去。比如我可以放一个; /etc/php/conf.d/upload.ini upload_max_filesize 64M post_max_size 64M memory_limit 256MPHP 启动时自动扫描这个目录所有 ini 文件都会被加载。这样既保持了二进制的可移植性又保留了配置灵活性。5.4 坑三UPX 压缩后二进制直接崩静态二进制的体积在一二十到七八十 MB 之间随着扩展增多会继续膨胀。我起初想用 UPX 给 PHP 二进制做一层压缩期望能从 45MB 压到 18MB 左右。结果压缩后的二进制在部分内核版本上运行时直接 Segmentation Fault。原因大家讨论得比较多大致是 UPX 解压时动态构造内存页的方式和 musl 静态二进制存在兼容性隐患。所以现在我的经验是不要对 PHP 静态二进制做 UPX 压缩老老实实strip就够了。体积大就大一点稳定性第一。5.5 坑四FPM 模式下的用户解析如果你编译了--enable-fpm那么静态 php-fpm 二进制在启动时如果配置user www-data而目标机器的/etc/passwd里没有这个用户就会直接启动失败或退出。传统 PHP 安装包通常会创建www-data用户但静态二进制不会干这种事。处理方式要么在部署脚本里预先创建用户要么 FPM 配置里直接用user nobody。nobody 用户几乎在所有 Linux 系统上存在做隔离足够用。这一点在写部署文档时务必提醒客户不然对方拿到二进制之后容易卡在这一步以为是二进制坏了。5.6 坑五ext-posix 之类的“编译期 vs 运行期”差异静态二进制一旦编译完成功能集合就固定了。运行期的dl()函数形同虚设因为你没法在系统里放任意.so扩展。以前那种“临时装一个 redis.so改一下 php.ini重启 FPM”的应急手段在静态二进制里不存在。这既是约束也是优势。约束在于你必须提前想清楚项目需要哪些扩展优势在于任何人拿到这个二进制运行行为都跟你测试时完全一致不会因为目标机器上的某个扩展版本不一致导致诡异死机。6. 进阶外部扩展redis / apcu静态编译的正确姿势6.1 内置扩展和外部扩展的编译差异PHP 源码树的ext/目录里自带很多官方扩展比如 mbstring、mysqlnd、openssl、sqlite、bcmath、zip。这些扩展的静态编译只需要在 configure 时加上--enable-xxx或--with-xxx构建系统会直接把它们纳入内核符号表非常省事。但实际项目里往往还需要 PECL 仓库的外部扩展比如redis、apcu、imagick、swoole。这些扩展不在 PHP 源码树里需要先pecl download或 git clone 拿到源码再通过phpize生成自己的 configure 脚本然后单独编译。编译出来的默认产物是.so如果想把它们融进静态二进制需要让它们生成静态.a并注册进 PHP 内核。这个流程比内置扩展复杂一个量级因为 PHP 的构建系统在生成最终链接命令时不会自动发现这些外部扩展的符号。6.2 手写外部扩展静态链接的通用套路以 redis 扩展为例手写的大致思路是先把扩展源码编译成静态库pecl download redis cd redis-6.0.2 # 使用构建环境里的 phpize 生成 configure phpize ./configure --with-php-config/usr/local/php/bin/php-config --enable-redisstatic make执行完以后modules/目录下会生成redis.a和redis.so。redis.a是我们要的静态库。接下来要把这个静态库加入 PHP 最终链接阶段。做法是在 PHP 源码树的configure配置里通过EXTENSION_LIBS和CFLAGS把它带进去。一般的做法是修改或生成一个config.nice文件把--enable-redisstatic和--with-php-config...都加进最终 configure 命令同时让 PHP 构建系统知道这个扩展的源文件和动态库路径。这里有一句非常值得写给后来者的话手写这套流程极其容易受 PHP 小版本和扩展版本的影响经常出现编译通过、链接失败或者链接成功、运行时符号找不到的情况。我不是劝退你研究底层而是提醒你如果目标是尽快上线可以直接借助现成封装。6.3 省心路线static-php-cli 这类工具已经替你踩完坑有一个开源项目叫static-php-cliGitHub 上搜 crazywhalecc/static-php-cli 就能找到它本质上把整套 PHP 静态编译和外部扩展静态链接的流程做了产品化封装。它不仅支持 redis、apcu、swoole还支持 imagick、pcntl、event 等一堆常用扩展并且自动处理依赖库的静态编译顺序。使用极其简单拉下来以后直接执行它的构建命令指定 PHP 版本、扩展列表、目标架构它会把 openssl、curl、sqlite、redis 等依赖全部编排好最后在dist/目录下生成你想要的静态二进制。我在自己的生产交付方案里是这样分工的团队自研的 PHP 版本管理和核心扩展配置我仍然自己控制但外部扩展的静态链接我直接交给 static-php-cli。这样既保住了对构建过程的掌控力又节省了大量调试时间。另外还要点名 FrankenPHP它是 Caddy 作者主导的“PHP 应用服务器”项目把 Caddy、PHP、静态链路整合成一个可执行文件。如果你要分发的是现代 PHP Web 应用可以进一步了解这个方案它比单纯的 CLI 二进制更贴近实际生产。6.4 我个人的倾向与取舍折腾到这里我给自己的项目定了一条原则要功能完整、扩展丰富、长期维护选 static-php-cli要深刻理解原理、完全掌控产物就亲自手搓一遍 configure 脚本。两种路线没有高下之分取决于你用这套方案的频率和深度。如果一年只做一两次交付没必要从零造轮子如果你是准备把它变成团队的基础设施那必须吃透每个参数的含义。我最初是自己手搓因为我对 PHP 内核链接机制好奇踩完 Redis 扩展的坑之后我反而理解了为什么社区会有 static-php-cli 这种工具存在。使用别人的工具不可耻可耻的是把工具当成黑盒却不去理解背后的约束导致上了生产之后手足无措。7. 这套方案在我项目里的实际躺平效果我把这套“Docker 一键编译静态 PHP”的流程接入 CI 之后客户交付从一项“技术活”变成了“体力活”。每次发新版本流水线自动构建出linux/amd64和linux/arm64两个原生二进制我把产物传到网盘或者直接 scp 给客户的服务器再附带一份不到 20 行的部署说明放二进制、放配置目录、创建 nobody 用户、写 systemd 单元文件完事。过去那种“客户说 PHP 报错我远程上去一看发现是扩展缺失”的噩梦基本消失了。因为二进制是自包含的行为在每台机器上都一样。客户甚至不太关心你有没有 PHP他们只关心这个程序能不能跑而这恰恰是 Go 式分发的精髓。也有一个不得不提醒的地方PHP 静态二进制的体积确实比 Go 大得多一般会在 30MB 到 80MB 之间配置和证书也必须通过conf.d目录和指定路径注入。所以它更适合“交付固定应用”而不是“交付一套通用 PHP 环境”。如果客户需要一套通用的 PHP 运行环境继续用容器或者传统安装包反而更合适。我对这套流程最直观的体会是技术选型没有银弹但“把环境装进产物”的思路在各个语言里都值得复制。Go 把一个运行时塞进一个文件PHP 也可以把解释器、扩展、依赖塞进一个文件。你只需要在构建期多想一步部署期的烦恼就能少一多半。最后留一个小建议找一台干净测试机先把php -v的静态二进制跑通再上php -S 0.0.0.0:8080跑一个简单 Web 应用最后再考虑 FPM、redis 这些进阶模块。一步步来踩坑的代价会小很多。
