FrankenPHP 嵌入式部署指南将 PHP 应用打包为独立可执行文件【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphpFrankenPHP 支持将 PHP 应用的源码与静态资源直接嵌入到一个静态、自包含的二进制文件中让应用本身、PHP 解释器以及生产级 Web 服务器 Caddy 融为一体。本文基于官方文档 docs/tr/embed.md结合仓库源码深入讲解应用预处理、Linux/其他平台二进制构建、启动运行与分发压缩的全过程帮助你掌握从源码到可直接分发部署的单一可执行文件的完整实操链路。核心原理一个二进制包含全部运行环境FrankenPHP 的嵌入特性在仓库源码中有非常直接的体现。embed.go 通过 Go 的//go:embed指令将两个构建产物打包进二进制//go:embed app.tar var embeddedApp []byte //go:embed app_checksum.txt var embeddedAppChecksum []byteapp.tar是应用源码的归档文件app_checksum.txt是校验和。在程序init()阶段FrankenPHP 会把归档解压到临时目录中默认解压路径为os.TempDir() frankenphp_ checksum校验和作为后缀保证同一应用解压到稳定位置也可以通过编译期-ldflags -X github.com/dunglas/frankenphp.EmbeddedAppPath/app覆盖固定解压路径适用于应用内含 OPcache 文件缓存等引用了绝对路径的预编译产物场景。解压完成后caddy/php-server.go 在启动php-server命令时会执行os.Chdir(frankenphp.EmbeddedAppPath)将工作目录切换到嵌入应用目录随后检查目录下是否存在php.ini与Caddyfile存在则自动加载见下文自定义配置小节。这意味着最终交付给用户的只是一个可执行文件运行时的 PHP 版本、扩展、Web 服务器与配置都已内嵌完毕。第一步准备你的应用在构建自包含二进制之前请确保应用已为嵌入做好准备。建议完成以下操作安装应用的生产依赖production dependencies导出dump自动加载器autoloader启用应用的生产模式如果有移除.git、测试等非必需文件减小最终二进制体积。以 Symfony 应用为例官方文档给出了一套完整的准备命令# 导出项目去掉 .git/ 等目录 mkdir $TMPDIR/my-prepared-app git archive HEAD | tar -x -C $TMPDIR/my-prepared-app cd $TMPDIR/my-prepared-app # 设置正确的环境变量 echo APP_ENVprod .env.local echo APP_DEBUG0 .env.local # 删除测试及其他非必需文件以节省空间 # 也可以在 .gitattributes 中为这些文件添加 export-ignore 属性 rm -Rf tests/ # 安装依赖 composer install --ignore-platform-reqs --no-dev -a # 优化 .env composer dump-env prod这套流程的核心目标是瘦身 固定生产环境git archive HEAD只导出当前提交内容避免.git历史进入归档composer install --no-dev -a只安装生产依赖并优化自动加载composer dump-env prod将环境变量固化进.env.local.php确保运行时行为可复现。自定义配置Caddyfile 与 php.ini要定制运行配置可以在待嵌入应用的主目录上例中的$TMPDIR/my-prepared-app中放置Caddyfile和php.ini文件。从源码看这一机制在 caddy/php-server.go 中实现启动时若检测到嵌入目录存在php.ini会将该目录追加到PHP_INI_SCAN_DIR环境变量若检测到Caddyfile则直接以 Caddyfile 模式加载配置。也就是说你的自定义服务器配置路由、域名、TLS、重写规则等和 PHP 运行时配置都会随二进制一起分发。完整的 Caddyfile 指令说明可参考 config.md。第二步构建 Linux 二进制构建 Linux 二进制最简单的方式是使用项目提供的基于 Docker 的静态编译镜像。1. 编写 static-build.Dockerfile在应用仓库中创建名为static-build.Dockerfile的文件# static-build.Dockerfile FROM --platformlinux/amd64 dunglas/frankenphp:static-builder-gnu # 如果你打算在 musl-libc 系统上运行二进制请改用 static-builder-musl # 复制你的应用 WORKDIR /go/src/app/dist/app COPY . . # 构建静态二进制 WORKDIR /go/src/app/ RUN EMBEDdist/app/ ./build-static.sh[!CAUTION]部分.dockerignore文件例如 Symfony Docker 默认提供的.dockerignore会忽略vendor/目录和.env文件。构建前务必调整或删除.dockerignore否则嵌入的应用会缺少依赖。2. 执行构建docker build -t static-app -f static-build.Dockerfile .3. 提取二进制文件docker cp $(docker create --name static-app-tmp static-app):/go/src/app/dist/frankenphp-linux-x86_64 my-app ; docker rm static-app-tmp构建完成后当前目录下的my-app就是最终的自包含二进制文件。关于镜像底层的细节static-builder-gnu.Dockerfile基于 CentOS 7 并启用 GNU 工具链SPC_LIBCglibc适合 glibc 系发行版static-builder-musl.Dockerfile基于 AlpineSPC_LIBCmusl产物可运行在更广泛的轻量容器与发行版上。两者的构建入口都是根目录的 build-static.sh 脚本。第三步为其他操作系统构建二进制如果不想使用 Docker或者需要构建 macOS 二进制可以直接使用仓库提供的 shell 脚本git clone https://github.com/php/frankenphp cd frankenphp EMBED/path/to/your/app ./build-static.sh构建产物位于dist/目录下文件名为frankenphp-os-arch例如frankenphp-mac-arm64。从 build-static.sh 源码可以看到EMBED变量指向待嵌入应用路径脚本会将其转换为绝对路径并通过--with-frankenphp-app${EMBED}参数传给 static-php-cli 构建系统最终把应用归档进app.tar。该脚本同样适用于 Linux其他类 Unix 系统Docker 版静态编译器内部调用的正是它。第四步运行你的独立应用构建完成后my-app或其他平台上的dist/frankenphp-os-arch已经包含你的完整应用。启动 Web 应用./my-app php-server如果你的应用包含 worker 脚本可以这样启动 worker 模式./my-app php-server --worker public/index.php要启用 HTTPS自动生成 Lets Encrypt 证书、HTTP/2 和 HTTP/3指定要使用的域名./my-app php-server --domain localhost还可以直接运行嵌入在二进制中的 PHP CLI 脚本./my-app php-cli bin/consolephp-server与php-cli这两个命令都注册在 caddy/php-cli.go 与 caddy/php-server.go 中。php-server是一个开箱即用的生产级服务器命令支持的参数包括--domain域名指定后切换至 HTTPS 端口、--root站点根目录、--listen监听地址、--workerworker 脚本可带,数量指定进程数、--watch热重载监听、--access-log访问日志、--mercure内置 Mercure hub与--no-compress关闭 Zstandard/Brotli/Gzip 压缩等。当检测到嵌入应用时该命令会自动切换到嵌入目录并加载其中的配置因此上述命令无需额外参数即可直接服务嵌入的应用。PHP 扩展自动按项目需求构建在嵌入模式下构建脚本会智能选择要编译的 PHP 扩展若嵌入目录存在composer.json、composer.lock且依赖已安装存在vendor/composer/installed.json脚本会调用spc dump-extensions从项目的composer.json中提取所需扩展剔除默认扩展集后输出实现项目需要什么就编译什么若不存在composer.json则编译默认扩展集见 build-static.sh 中的defaultExtensions涵盖 opcache、mbstring、pdo_mysql、redis 等常用扩展若需手动指定可通过PHP_EXTENSIONS环境变量覆盖。自定义构建要定制二进制内容如扩展列表、PHP 版本等请阅读静态构建文档。build-static.sh 中列出并支持以下环境变量可用于docker build和脚本两种方式FRANKENPHP_VERSION使用的 FrankenPHP 版本PHP_VERSION使用的 PHP 版本默认取最新版本PHP_EXTENSIONS要编译的 PHP 扩展列表PHP_EXTENSION_LIBS为扩展提供额外能力的库列表XCADDY_ARGS传给 xcaddy 的参数用于添加额外 Caddy 模块EMBED要嵌入二进制的 PHP 应用路径CLEAN设置后清空缓存从零构建 libphp 及全部依赖DEBUG_SYMBOLS设置后保留调试符号COMPRESSLinux 下设置后使用 UPX 压缩产物MIMALLOC设置后使用 mimalloc 作为内存分配器RELEASE仅维护者设置后将产物上传到 GitHub Release。分发与压缩Linux 下可在构建时设置COMPRESS1环境变量用 UPX 压缩产物大幅减小二进制体积需要注意的是当同时设置DEBUG_SYMBOLS时压缩会被跳过见 build-static.sh 中--with-upx-pack的启用条件。macOS 下可在发送前自行压缩文件以减小体积官方推荐使用xz。总结借助 FrankenPHP 的嵌入能力PHP 应用可以脱离传统的服务器 解释器 依赖安装部署模型直接交付为单一可执行文件。整个流程可以归纳为准备应用生产依赖 环境变量固化 瘦身→ 编写static-build.Dockerfile或直接运行build-static.sh构建 → 用php-server/php-cli运行 → 按需用 UPX / xz 压缩后分发。无论是 Symfony、Laravel 还是其他 Composer 项目都可以基于这套流程快速产出自包含、可移植的发布物。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FrankenPHP 嵌入式部署指南：将 PHP 应用打包为独立可执行文件
FrankenPHP 嵌入式部署指南将 PHP 应用打包为独立可执行文件【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphpFrankenPHP 支持将 PHP 应用的源码与静态资源直接嵌入到一个静态、自包含的二进制文件中让应用本身、PHP 解释器以及生产级 Web 服务器 Caddy 融为一体。本文基于官方文档 docs/tr/embed.md结合仓库源码深入讲解应用预处理、Linux/其他平台二进制构建、启动运行与分发压缩的全过程帮助你掌握从源码到可直接分发部署的单一可执行文件的完整实操链路。核心原理一个二进制包含全部运行环境FrankenPHP 的嵌入特性在仓库源码中有非常直接的体现。embed.go 通过 Go 的//go:embed指令将两个构建产物打包进二进制//go:embed app.tar var embeddedApp []byte //go:embed app_checksum.txt var embeddedAppChecksum []byteapp.tar是应用源码的归档文件app_checksum.txt是校验和。在程序init()阶段FrankenPHP 会把归档解压到临时目录中默认解压路径为os.TempDir() frankenphp_ checksum校验和作为后缀保证同一应用解压到稳定位置也可以通过编译期-ldflags -X github.com/dunglas/frankenphp.EmbeddedAppPath/app覆盖固定解压路径适用于应用内含 OPcache 文件缓存等引用了绝对路径的预编译产物场景。解压完成后caddy/php-server.go 在启动php-server命令时会执行os.Chdir(frankenphp.EmbeddedAppPath)将工作目录切换到嵌入应用目录随后检查目录下是否存在php.ini与Caddyfile存在则自动加载见下文自定义配置小节。这意味着最终交付给用户的只是一个可执行文件运行时的 PHP 版本、扩展、Web 服务器与配置都已内嵌完毕。第一步准备你的应用在构建自包含二进制之前请确保应用已为嵌入做好准备。建议完成以下操作安装应用的生产依赖production dependencies导出dump自动加载器autoloader启用应用的生产模式如果有移除.git、测试等非必需文件减小最终二进制体积。以 Symfony 应用为例官方文档给出了一套完整的准备命令# 导出项目去掉 .git/ 等目录 mkdir $TMPDIR/my-prepared-app git archive HEAD | tar -x -C $TMPDIR/my-prepared-app cd $TMPDIR/my-prepared-app # 设置正确的环境变量 echo APP_ENVprod .env.local echo APP_DEBUG0 .env.local # 删除测试及其他非必需文件以节省空间 # 也可以在 .gitattributes 中为这些文件添加 export-ignore 属性 rm -Rf tests/ # 安装依赖 composer install --ignore-platform-reqs --no-dev -a # 优化 .env composer dump-env prod这套流程的核心目标是瘦身 固定生产环境git archive HEAD只导出当前提交内容避免.git历史进入归档composer install --no-dev -a只安装生产依赖并优化自动加载composer dump-env prod将环境变量固化进.env.local.php确保运行时行为可复现。自定义配置Caddyfile 与 php.ini要定制运行配置可以在待嵌入应用的主目录上例中的$TMPDIR/my-prepared-app中放置Caddyfile和php.ini文件。从源码看这一机制在 caddy/php-server.go 中实现启动时若检测到嵌入目录存在php.ini会将该目录追加到PHP_INI_SCAN_DIR环境变量若检测到Caddyfile则直接以 Caddyfile 模式加载配置。也就是说你的自定义服务器配置路由、域名、TLS、重写规则等和 PHP 运行时配置都会随二进制一起分发。完整的 Caddyfile 指令说明可参考 config.md。第二步构建 Linux 二进制构建 Linux 二进制最简单的方式是使用项目提供的基于 Docker 的静态编译镜像。1. 编写 static-build.Dockerfile在应用仓库中创建名为static-build.Dockerfile的文件# static-build.Dockerfile FROM --platformlinux/amd64 dunglas/frankenphp:static-builder-gnu # 如果你打算在 musl-libc 系统上运行二进制请改用 static-builder-musl # 复制你的应用 WORKDIR /go/src/app/dist/app COPY . . # 构建静态二进制 WORKDIR /go/src/app/ RUN EMBEDdist/app/ ./build-static.sh[!CAUTION]部分.dockerignore文件例如 Symfony Docker 默认提供的.dockerignore会忽略vendor/目录和.env文件。构建前务必调整或删除.dockerignore否则嵌入的应用会缺少依赖。2. 执行构建docker build -t static-app -f static-build.Dockerfile .3. 提取二进制文件docker cp $(docker create --name static-app-tmp static-app):/go/src/app/dist/frankenphp-linux-x86_64 my-app ; docker rm static-app-tmp构建完成后当前目录下的my-app就是最终的自包含二进制文件。关于镜像底层的细节static-builder-gnu.Dockerfile基于 CentOS 7 并启用 GNU 工具链SPC_LIBCglibc适合 glibc 系发行版static-builder-musl.Dockerfile基于 AlpineSPC_LIBCmusl产物可运行在更广泛的轻量容器与发行版上。两者的构建入口都是根目录的 build-static.sh 脚本。第三步为其他操作系统构建二进制如果不想使用 Docker或者需要构建 macOS 二进制可以直接使用仓库提供的 shell 脚本git clone https://github.com/php/frankenphp cd frankenphp EMBED/path/to/your/app ./build-static.sh构建产物位于dist/目录下文件名为frankenphp-os-arch例如frankenphp-mac-arm64。从 build-static.sh 源码可以看到EMBED变量指向待嵌入应用路径脚本会将其转换为绝对路径并通过--with-frankenphp-app${EMBED}参数传给 static-php-cli 构建系统最终把应用归档进app.tar。该脚本同样适用于 Linux其他类 Unix 系统Docker 版静态编译器内部调用的正是它。第四步运行你的独立应用构建完成后my-app或其他平台上的dist/frankenphp-os-arch已经包含你的完整应用。启动 Web 应用./my-app php-server如果你的应用包含 worker 脚本可以这样启动 worker 模式./my-app php-server --worker public/index.php要启用 HTTPS自动生成 Lets Encrypt 证书、HTTP/2 和 HTTP/3指定要使用的域名./my-app php-server --domain localhost还可以直接运行嵌入在二进制中的 PHP CLI 脚本./my-app php-cli bin/consolephp-server与php-cli这两个命令都注册在 caddy/php-cli.go 与 caddy/php-server.go 中。php-server是一个开箱即用的生产级服务器命令支持的参数包括--domain域名指定后切换至 HTTPS 端口、--root站点根目录、--listen监听地址、--workerworker 脚本可带,数量指定进程数、--watch热重载监听、--access-log访问日志、--mercure内置 Mercure hub与--no-compress关闭 Zstandard/Brotli/Gzip 压缩等。当检测到嵌入应用时该命令会自动切换到嵌入目录并加载其中的配置因此上述命令无需额外参数即可直接服务嵌入的应用。PHP 扩展自动按项目需求构建在嵌入模式下构建脚本会智能选择要编译的 PHP 扩展若嵌入目录存在composer.json、composer.lock且依赖已安装存在vendor/composer/installed.json脚本会调用spc dump-extensions从项目的composer.json中提取所需扩展剔除默认扩展集后输出实现项目需要什么就编译什么若不存在composer.json则编译默认扩展集见 build-static.sh 中的defaultExtensions涵盖 opcache、mbstring、pdo_mysql、redis 等常用扩展若需手动指定可通过PHP_EXTENSIONS环境变量覆盖。自定义构建要定制二进制内容如扩展列表、PHP 版本等请阅读静态构建文档。build-static.sh 中列出并支持以下环境变量可用于docker build和脚本两种方式FRANKENPHP_VERSION使用的 FrankenPHP 版本PHP_VERSION使用的 PHP 版本默认取最新版本PHP_EXTENSIONS要编译的 PHP 扩展列表PHP_EXTENSION_LIBS为扩展提供额外能力的库列表XCADDY_ARGS传给 xcaddy 的参数用于添加额外 Caddy 模块EMBED要嵌入二进制的 PHP 应用路径CLEAN设置后清空缓存从零构建 libphp 及全部依赖DEBUG_SYMBOLS设置后保留调试符号COMPRESSLinux 下设置后使用 UPX 压缩产物MIMALLOC设置后使用 mimalloc 作为内存分配器RELEASE仅维护者设置后将产物上传到 GitHub Release。分发与压缩Linux 下可在构建时设置COMPRESS1环境变量用 UPX 压缩产物大幅减小二进制体积需要注意的是当同时设置DEBUG_SYMBOLS时压缩会被跳过见 build-static.sh 中--with-upx-pack的启用条件。macOS 下可在发送前自行压缩文件以减小体积官方推荐使用xz。总结借助 FrankenPHP 的嵌入能力PHP 应用可以脱离传统的服务器 解释器 依赖安装部署模型直接交付为单一可执行文件。整个流程可以归纳为准备应用生产依赖 环境变量固化 瘦身→ 编写static-build.Dockerfile或直接运行build-static.sh构建 → 用php-server/php-cli运行 → 按需用 UPX / xz 压缩后分发。无论是 Symfony、Laravel 还是其他 Composer 项目都可以基于这套流程快速产出自包含、可移植的发布物。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考