使用 FrankenPHP 将 PHP 项目打包为二进制可执行文件

FrankenPHP 是一个现代化的 PHP 应用服务器，基于 Caddy Web 服务器构建，支持将 PHP 项目打包为独立的二进制可执行文件。本指南将详细介绍如何使用 FrankenPHP 将 PHP 项目打包为二进制文件，涵盖准备工作、构建流程和使用方法。

准备工作

在打包之前，需要优化 PHP 项目以确保生成高效的二进制文件。以下是关键步骤：

1. 依赖管理：

• 使用 Composer 安装生产环境所需的依赖，排除开发依赖：
  bash composer install --no-dev --optimize-autoloader
• 优化自动加载以提高性能。

1. 环境配置：

• 设置生产环境变量，确保应用以生产模式运行：
  bash echo "APP_ENV=prod" > .env echo "APP_DEBUG=0" >> .env
• 禁用调试模式以减少资源占用。

1. 清理非必要文件：

• 删除 .git 目录、测试文件和其他非生产必需的资源：
  bash rm -rf tests/ .git/ docs/
• 确保项目目录精简，仅包含运行所需的文件。

1. 项目导出（可选）：

• 如果使用 Git，可以导出一个干净的项目副本：
  bash mkdir -p /tmp/prepared-app git archive HEAD | tar -x -C /tmp/prepared-app cd /tmp/prepared-app

使用 Docker 构建 Linux 二进制文件

FrankenPHP 提供了基于 Docker 的构建流程，适用于 Linux 平台，是最简单的方式。

1. 创建 Dockerfile：
   在项目根目录创建一个名为 static-build.Dockerfile 的文件，内容如下：

   FROM dunglas/frankenphp:static-builder
   WORKDIR /go/src/app/dist/app
   COPY . .
   WORKDIR /go/src/app/
   RUN EMBED=dist/app/ \
       PHP_EXTENSIONS=ctype,iconv,pdo_sqlite \
       ./build-static.sh

• 说明：
  • EMBED 指定项目路径。
  • PHP_EXTENSIONS 列出所需的 PHP 扩展（如 pdo_mysql、curl 等），根据项目需求调整。
  • 注意检查 .dockerignore 文件，确保不排除 vendor 目录或 .env 文件。

1. 构建镜像：
   运行以下命令构建 Docker 镜像：

   docker build -t my-app-builder -f static-build.Dockerfile .

3. 提取二进制文件：
   从容器中提取生成的可执行文件：

   docker create --name app-builder my-app-builder
   docker cp app-builder:/go/src/app/dist/frankenphp-linux-x86_64 my-app
   docker rm app-builder

• 生成的二进制文件名为 my-app，位于当前目录。

为其他操作系统构建（macOS 或自定义需求）

如果需要为 macOS 构建二进制文件，或不希望使用 Docker，可以直接使用 FrankenPHP 的源码构建。

1. 克隆 FrankenPHP 源码：

   git clone https://github.com/php/frankenphp
   cd frankenphp

2. 运行构建脚本：
   指定项目路径和所需 PHP 扩展，执行构建：

   EMBED=/path/to/your/app \
   PHP_EXTENSIONS=ctype,iconv,pdo_sqlite \
   ./build-static.sh

• /path/to/your/app 是你的 PHP 项目路径。
• 生成的二进制文件位于 dist/ 目录，命名为 frankenphp-<os>-<arch>（如 frankenphp-darwin-x86_64）。

1. 注意事项：

• macOS：建议使用 xz 压缩最终二进制文件以减小体积：
  bash xz -9 dist/frankenphp-darwin-x86_64
• Windows：推荐使用 WSL（Windows Subsystem for Linux）运行 FrankenPHP。
• ARM 架构：需指定正确的平台参数。

使用二进制文件

生成的可执行文件集成了 PHP 解释器、Caddy Web 服务器和你的应用代码，支持多种运行模式：

1. Web 服务器模式：
   启动内置 Web 服务器：

   ./my-app php-server

2. Worker 模式（适用于常驻内存的高性能应用）：

   ./my-app php-server --worker public/index.php

• 需确保入口文件（如 index.php）适配 Worker 模式。例如，对于 ThinkPHP，需将入口文件逻辑包裹在 frankenphp_handle_request 中：
  php require __DIR__ . '/../vendor/autoload.php'; frankenphp_handle_request(function () { $http = (new App())->http; $response = $http->run(); $response->send(); $http->end($response); });

1. HTTPS 支持：
   自动启用 Let』s Encrypt 证书：

   ./my-app php-server --domain example.com

4. CLI 模式：
   运行 PHP 命令行脚本：

   ./my-app php-cli bin/console cache:clear

优化与注意事项

1. 二进制文件优化：

• 压缩：Linux 使用 UPX 压缩，macOS 使用 xz 压缩以减小文件体积。
• PHP 扩展：仅包含必要的扩展（如 ctype、pdo_mysql），避免体积过大。
• OPcache：启用 OPcache 以提高性能：
  ini opcache.enable=1 opcache.memory_consumption=128

1. 常见问题解决：

• 体积过大：检查是否包含开发依赖，移除不必要的扩展，使用更高压缩级别。
• 启动失败：验证环境变量、文件权限，确保必要扩展已包含。
• 性能问题：优化自动加载，调整 Worker 数量，启用 OPcache。

结语

通过 FrankenPHP，你可以将 PHP 项目打包为单一的二进制可执行文件，简化部署流程并提升运行效率。这种方式特别适合需要保护源代码或在多平台快速部署的场景。更多信息可参考 FrankenPHP 官方文档：https://frankenphp.dev。