FrankenPHP 集成 Laravel 完整实战指南Docker 部署、本地运行、Octane 加速与独立二进制打包【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp导读本文基于 FrankenPHP 官方文档中的 Laravel 集成指南docs/fr/laravel.md系统讲解如何在 FrankenPHP 这一现代 PHP 应用服务器上运行 Laravel 应用。FrankenPHP 基于 Caddy 构建将 PHP 解释器直接嵌入 Web 服务器无需 PHP-FPM 即可运行。通过本文你将掌握四种 Laravel 部署形态Docker 容器化运行、本地二进制直跑、借助 Laravel Octane 进入常驻内存的 worker 高性能模式以及将整个 Laravel 应用连同 PHP 解释器和 Caddy 打包成单一可执行文件进行分发。概览为什么 Laravel 与 FrankenPHP 天然契合FrankenPHP 是使用 Go 编写的现代 PHP 应用服务器其核心创新在于将 PHP 直接嵌入 Caddy Web 服务器进程见 caddy/caddy.go 中的模块注册逻辑。对 Laravel 开发者而言这意味着无需 PHP-FPMphp_server指令由 FrankenPHP 自己的模块处理PHP 解释器就在进程内worker 模式常驻内存应用启动一次后驻留内存请求处理开销极小Laravel Octane 正是基于此机制为 Laravel 提供官方支持开箱即用的现代 HTTP 能力自动 HTTPS、HTTP/2、HTTP/3 均由底层 Caddy 提供。FrankenPHP 官方文档在 README.md 中明确说明其 worker 模式与 Laravel、Symfony 有官方集成让这些框架的应用运行得更快。下面按从简到繁的顺序展开四种部署方式。方式一通过 Docker 部署 Laravel 应用对于 Laravel 应用官方 Docker 镜像的使用极其简单——只需把项目挂载到容器的/app目录即可。在 Laravel 项目根目录执行docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp各参数的含义-p 80:80暴露 HTTP 端口-p 443:443暴露 HTTPS 端口Caddy 会自动为localhost生成自签名证书为公网域名自动申请 Lets Encrypt 证书-p 443:443/udp暴露 HTTP/3基于 QUIC所需的 UDP 端口-v $PWD:/app将当前 Laravel 项目目录挂载到容器的/app即 Docker 镜像约定的应用根目录。启动后访问https://localhost即可。官方文档特别提醒见 docs/fr/README.md不要使用https://127.0.0.1应使用https://localhost并接受自签名证书如需更换域名可通过环境变量SERVER_NAME实现。镜像内置的默认 caddy/frankenphp/Caddyfile 展示了容器内实际生效的配置骨架全局块中注入{$CADDY_GLOBAL_OPTIONS}与{$FRANKENPHP_CONFIG}站点块使用{$SERVER_NAME:localhost}、root {$SERVER_ROOT:public/}以及encode zstd br gzip默认开启 Zstandard、Brotli、Gzip 三种压缩最后通过php_server指令运行 PHP 脚本。这解释了为什么仅挂载目录即可运行 Laravel——默认站点根目录指向public/与 Laravel 的入口结构一致。方式二本地安装并配置 Caddyfile 运行 Laravel1. 下载二进制从官方发布的 README.md 中下载对应平台Linux / macOS的静态二进制。官方为开发场景提供的静态二进制内置 PHP 8.4 及大部分常用扩展开箱即用。2. 编写 Caddyfile在 Laravel 项目根目录创建名为Caddyfile的文件内容如下{ frankenphp } # 你的服务器域名 localhost { # 将站点根目录指向 public/ 文件夹 root public/ # 启用压缩可选 encode zstd br gzip # 运行 public/ 目录下的 PHP 脚本并托管静态资源 php_server { try_files {path} index.php } }配置要点说明全局块中的frankenphp选项用于启用 FrankenPHP 模块其中还可以配置num_threads、max_threads、worker等参数完整参数见 docs/fr/config.mdroot public/对应 Laravel 的公开入口目录SERVER_ROOT环境变量的默认值也正是public/见 caddy/caddy.go 中的defaultDocumentRoot常量try_files {path} index.php是 Laravel 前端控制器模式的经典写法先尝试匹配真实路径否则回退到index.php由 Laravel 路由接管encode zstd br gzip依次启用 Zstandard、Brotli、Gzip 压缩可按需裁剪。3. 启动在 Laravel 项目根目录执行frankenphp runFrankenPHP 默认会在当前目录查找Caddyfile。从源码角度看php_server指令在 caddy/caddy.go 中被注册为位于file_server之前执行的处理器指令因此它能优先处理 PHP 请求、再将静态资源交给file_server。php_server实际上是若干 Caddy 路由规则的组合目录重定向、index 文件回退、.php请求分流等php指令则是更底层的原语——如需完全控制请求分发可阅读 docs/fr/config.md 中的等价路由展开说明。方式三使用 Laravel Octane 进入 worker 高性能模式FrankenPHP 的 worker 模式允许应用启动一次并常驻内存配合 Laravel Octane 的官方集成可以显著降低每个请求的引导开销。安装 Octane通过 Composer 安装composer require laravel/octane安装完成后执行 Artisan 命令octane:install并显式指定 FrankenPHP 作为服务器php artisan octane:install --serverfrankenphp该命令会生成 Octane 的配置文件config/octane.php。启动 Octane 服务器通过octane:frankenphp命令启动php artisan octane:frankenphpoctane:frankenphp命令支持的选项如下默认值以文档为准选项作用默认值--host服务器绑定的 IP 地址127.0.0.1--port服务器监听端口8000--admin-portCaddy 管理接口端口2019--workers处理请求的 worker 数量auto--max-requests处理多少请求后重启服务器用于缓解内存泄漏500--caddyfileFrankenPHPCaddyfile文件的路径Octane 内置的模板 Caddyfile--https启用 HTTPS、HTTP/2、HTTP/3并自动生成/续期证书关闭--http-redirect启用 HTTP 到 HTTPS 的重定向仅在传入--https时生效关闭--watch应用文件变更时自动重启服务器关闭--poll使用文件系统轮询方式监听适用于网络文件系统关闭--log-level记录指定级别及以上的日志使用 Caddy 原生 logger—[!TIP] 如果需要结构化 JSON 日志便于对接日志分析平台请显式传入--log-level选项。--workers auto在底层对应 FrankenPHP 默认按每 CPU 启动约 2 个 worker 线程的策略而--max-requests对应 docs/fr/config.md 中描述的max_requests机制——线程处理完指定数量的请求后整体重启清空内存与状态其余线程在此期间继续服务是应对不可控内存泄漏的务实手段。关于 worker 模式更底层的原理frankenphp_handle_request()、superglobal 行为、失败重启策略等可继续阅读 docs/fr/worker.md。方式四将 Laravel 应用打包为独立二进制借助 FrankenPHP 的应用嵌入功能可以把 Laravel 应用连同 PHP 解释器、Caddy Web 服务器一起编译进单个静态可执行文件实现免环境依赖的分发。以下是官方文档给出的 Linux 打包全流程。1. 编写 static-build.Dockerfile在应用仓库中创建static-build.DockerfileFROM --platformlinux/amd64 dunglas/frankenphp:static-builder-gnu # 如果你打算在 musl-libc 系统上运行该二进制请改用 static-builder-musl # 复制你的应用 WORKDIR /go/src/app/dist/app COPY . . # 删除测试等无用文件以减小体积 # 也可以把这些文件加入 .dockerignore RUN rm -Rf tests/ # 复制 .env 文件 RUN cp .env.example .env # 将 APP_ENV 与 APP_DEBUG 调整为生产配置 RUN sed -i -e s/^APP_ENV.*/APP_ENVproduction/ -e s/^APP_DEBUG.*/APP_DEBUGfalse/ .env # 如有需要可在此处继续修改 .env # 安装依赖 RUN composer install --ignore-platform-reqs --no-dev -a # 构建静态二进制 WORKDIR /go/src/app/ RUN EMBEDdist/app/ ./build-static.sh[!CAUTION] 某些项目的.dockerignore会忽略vendor/目录和.env文件。构建前请务必调整或删除.dockerignore否则依赖与配置将不会被打包进二进制。EMBEDdist/app/是嵌入功能的核心构建脚本会将该目录下的应用源码与静态资源一并编译进二进制。更完整的嵌入说明包括应用预处理、自定义Caddyfile/php.ini、PHP_EXTENSIONS扩展定制、UPX 压缩等见 docs/fr/embed.md。2. 构建镜像docker build -t static-laravel-app -f static-build.Dockerfile .3. 提取二进制docker cp $(docker create --name static-laravel-app-tmp static-laravel-app):/go/src/app/dist/frankenphp-linux-x86_64 frankenphp ; docker rm static-laravel-app-tmp执行后当前目录下将出现名为frankenphp的可执行文件。4. 用内置 PHP CLI 完成初始化二进制内置了php-cli命令行为与 PHP CLI SAPI 一致见 caddy/php-cli.go 的命令定义。依次执行frankenphp php-cli artisan optimizefrankenphp php-cli artisan migratefrankenphp php-cli artisan key:generate分别完成缓存填充artisan optimize会生成路由、配置、事件等缓存、数据库迁移如有与应用密钥生成。5. 启动服务器frankenphp php-server应用即已就绪php-server是专为快速部署/演示设计的生产级命令定义见 caddy/php-server.go常用参数包括--domainexample.com指定域名自动启用 HTTPS含 HTTP/2、HTTP/3与证书自动签发--rootpath站点根目录--listenaddr自定义监听地址--worker/path/to/worker.php[,nb-workers]以 worker 模式启动--watch[glob]监听文件变更自动重启默认匹配./**/*.{env,php,twig,yaml,yml}--access-log/--debug/--no-compress/--mercure分别控制访问日志、调试日志、压缩默认开启 zstd/br/gzip与内置 Mercure hub。从源码看php-server在检测到二进制内嵌了应用EmbeddedAppPath非空时会自动chdir到内嵌目录并依次检查php.ini将其加入PHP_INI_SCAN_DIR与Caddyfile自动加载——这就是嵌入应用无需任何外部配置文件即可启动的原因见 caddy/php-server.go。更改存储路径关键注意点Laravel 默认将上传文件、缓存、日志等存放在应用内的storage/目录。这对嵌入二进制不适用因为每次新版本发布时应用会被解压到不同的临时目录数据会随之丢失。解决方式有二任选其一设置环境变量LARAVEL_STORAGE_PATH例如写入.env调用Illuminate\Foundation\Application::useStoragePath()方法。将存储路径指向临时目录之外的持久化位置即可。在独立二进制中运行 Octane甚至可以先把 Laravel Octane 应用打包成独立二进制再以 worker 模式运行。做法是先按上一节正确安装 Octane再按本节步骤完成打包最后执行PATH$PWD:$PATH frankenphp php-cli artisan octane:frankenphp[!CAUTION] 该命令要正常工作独立二进制必须命名为frankenphp因为 Octane 需要在 PATH 中找到名为frankenphp的可执行程序。命令前的PATH$PWD:$PATH正是为了让当前目录下的frankenphp可被找到。深入worker 模式与嵌入机制的源码支撑为了让上文结论可验证这里给出几条仓库源码证据便于读者深入研读模块注册caddy/caddy.go 注册了frankenphp全局选项、php与php_server指令并将二者的执行顺序置于file_server之前defaultDocumentRoot publicL15与defaultWatchPattern ./**/*.{env,php,twig,yaml,yml}L16两个常量分别对应 Laravel 的默认入口与--watch的默认监听范围php-cli 实现caddy/php-cli.go 剥离php-cli参数、还原 PHP CLI 的 argv 语义并在脚本路径不存在时自动重定向到内嵌应用目录最终调用frankenphp.ExecuteScriptCLI见根目录 cli.gophp-server 实现caddy/php-server.go 定义了--domain/--root/--listen/--worker/--watch/--access-log/--debug/--mercure/--no-compress全套参数并处理内嵌应用的目录切换、php.ini扫描与Caddyfile加载容器默认配置caddy/frankenphp/Caddyfile 展示了镜像内SERVER_NAME、SERVER_ROOT、CADDY_GLOBAL_OPTIONS、FRANKENPHP_CONFIG等环境变量如何注入配置以及php_server与Caddyfile.d/*.caddyfile的扩展机制。参考文档索引Laravel 集成完整指南docs/fr/laravel.md应用嵌入为独立二进制docs/fr/embed.mdCaddyfile 与 worker 配置详解docs/fr/config.mdworker 模式原理与自定义 worker 脚本docs/fr/worker.mdDocker 镜像用法docs/fr/docker.md项目总览与二进制下载docs/fr/README.md【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考