在 FrankenPHP 中运行 Laravel 应用：Docker、本地安装、Octane 与独立二进制完整指南

在 FrankenPHP 中运行 Laravel 应用Docker、本地安装、Octane 与独立二进制完整指南【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphpFrankenPHP 是一个基于 Caddy 构建的现代 PHP 应用服务器它把 PHP 解释器、生产级 Web 服务器与自动 HTTPS 融为一体。本文以 Laravel 为具体落点系统讲解四种运行与分发 Laravel 应用的方式官方 Docker 镜像、本地二进制 Caddyfile、基于 Worker 模式的 Laravel Octane 高性能运行以及把整套 Laravel 应用打包成可独立执行的静态二进制。阅读本文后你将掌握从开发到生产部署、再到离线分发的完整实战路径。本文对应的仓库文档为 docs/es/laravel.md英文原版见 docs/laravel.md其中涉及的所有命令与配置均以当前仓库实际内容为准。一、用 Docker 镜像快速启动 Laravel 应用FrankenPHP 官方 Docker 镜像内置了 PHP、Caddy 以及默认的Caddyfile配置见仓库中的 caddy/frankenphp/Caddyfile。要运行一个 Laravel 项目只需把项目目录挂载到容器的/app目录docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp从 Laravel 项目根目录执行该命令即可。命令中各部分的含义-p 80:80映射 HTTP 端口-p 443:443映射 HTTPS 端口Caddy 会自动为localhost签发本地证书访问时使用https://localhost并接受自签名证书即可-p 443:443/udp映射 HTTP/3QUIC使用的 UDP 端口-v $PWD:/app把当前 Laravel 项目挂载到容器内的/app而 caddy/frankenphp/Caddyfile 中默认的root指向public/php_server指令会执行 PHP 文件并托管静态资源。[!TIP] 该镜像自带的Caddyfile还预留了SERVER_NAME、SERVER_ROOT、FRANKENPHP_CONFIG、CADDY_GLOBAL_OPTIONS等环境变量注入点并注释了 Mercure 与 Vulcain 模块的启用方式。修改站点配置更推荐通过环境变量或Caddyfile.d/*.caddyfile附加文件实现而不是直接改动镜像内配置。二、本地安装用 Caddyfile 运行 Laravel不想使用 Docker 时可以从官方发布的独立二进制入手。独立二进制自带 PHP 8.5 及多数常用扩展Linux 版本为静态链接无需安装任何系统依赖即可运行详见 README.md。下载对应你系统的二进制在 Laravel 项目根目录创建Caddyfile写入以下配置# Caddyfile { frankenphp } # 你的服务器域名 localhost { # 把 Web 根目录设置为 public/ root public/ # 启用压缩可选 encode zstd br gzip # 从 public/ 目录执行 PHP 文件并托管静态资源 php_server { try_files {path} index.php } }在 Laravel 项目根目录启动frankenphp run。这段配置对应的行为在 docs/config.md 中有更底层的解释php_server指令等价于一组 Caddy 路由——先为目录请求补尾部斜杠再通过try_files依次尝试请求路径、{path}/index.php与index.php把命中项重写为实际文件最后把*.php请求交给 FrankenPHP、其余交给file_server托管。这也是 Laravel 单入口public/index.php能够正常工作的原因。如果只是想快速演示或开发也可以不写Caddyfile直接使用php-server子命令见 caddy/php-server.gofrankenphp php-server --root public/三、Laravel Octane把应用常驻内存Laravel Octane 是 Laravel 官方的应用加速方案它让应用只引导bootstrap一次并常驻内存后续请求在毫秒级完成。FrankenPHP 的 Worker 模式正是 Octane 的底层支撑应用在 PHP 线程中长期存活请求到达时由frankenphp_handle_request()循环分发处理工作机制详见 docs/worker.md。安装与启动composer require laravel/octanephp artisan octane:install --serverfrankenphpoctane:install --serverfrankenphp会在应用内生成 Octane 配置文件并注册 FrankenPHP 服务器条目。启动命令为php artisan octane:frankenphpoctane:frankenphp命令支持的选项如下默认值以 Laravel Octane 官方实现为准选项作用默认值--host服务器绑定的 IP 地址127.0.0.1--port服务器监听端口8000--admin-portCaddy 管理 API 端口2019--workers处理请求的 Worker 数量auto自动探测--max-requests每个 Worker 处理多少请求后重启缓解内存泄漏500--caddyfile指定 FrankenPHP 的Caddyfile路径Laravel Octane 内置模板--https启用 HTTPS、HTTP/2、HTTP/3并自动签发与续期证书关闭--http-redirect启用 HTTP 到 HTTPS 的跳转仅在传--https时生效关闭--watch应用文件变化时自动重启服务器关闭--poll跨网络监视文件时改用文件系统轮询关闭--log-level按指定级别记录日志使用 Caddy 原生日志器关闭[!TIP] 需要结构化 JSON 日志例如接入日志分析平台时务必显式传入--log-level选项。关于--max-requests它对应 FrankenPHP 在 docs/config.md 中描述的max_requests机制PHP 并非为长驻进程设计库与旧代码存在内存泄漏风险时可在线程处理指定数量请求后将其整体重启清理全部内存与状态重启期间其他线程继续服务。四、把 Laravel 应用打包成独立二进制利用 FrankenPHP 的应用嵌入特性详见 docs/embed.md可以把 Laravel 应用连同 PHP 解释器、Caddy Web 服务器打包进一个自包含的静态二进制实现一个文件分发一个应用。以 Linux 为例按以下步骤操作1. 编写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 . . # 删除测试等无关文件以减小体积 # 也可以把这些文件加入 .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否则构建出的二进制将不包含应用依赖。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-tmp4. 填充缓存frankenphp php-cli artisan optimize5. 执行数据库迁移如有frankenphp php-cli artisan migrate6. 生成应用密钥frankenphp php-cli artisan key:generate7. 启动服务器frankenphp php-server应用即告就绪。这里用到的php-cli子命令在 caddy/php-cli.go 中实现它把参数透传给 PHP 的 CLI SAPI 执行当二进制内嵌了应用frankenphp.EmbeddedAppPath非空且脚本路径不是绝对路径时会自动在嵌入目录中解析目标脚本因此artisan等命令可以开箱即用。如需为其他操作系统如 macOS构建或想进一步定制扩展、PHP 版本请参考 docs/embed.md 与 docs/static.md。五、修改存储路径适配内嵌应用的持久化默认情况下Laravel 会把上传文件、缓存、日志等写入应用内的storage/目录。这对内嵌应用并不合适——因为每次发布新版本二进制会被解压到不同的临时目录存储内容会随之丢失。解决办法是把存储目录指向临时目录之外的固定位置设置环境变量LARAVEL_STORAGE_PATH例如写入.env或在代码中调用Illuminate\Foundation\Application::useStoragePath()方法。二者任选其一即可让数据库迁移、缓存与用户上传数据跨版本持久保存。六、为 Laravel 应用接入 Mercure 实时推送Mercure 是一种基于 HTTP 的实时事件推送协议也是 WebSocket 的轻量替代方案现代浏览器原生支持。FrankenPHP 内置了 Mercure Hub仓库根目录的 docs/mercure.md 有完整说明界面如下因此 Laravel 应用无需额外部署 Hub 服务即可获得实时能力。未使用 Octane 时按 docs/mercure.md 在Caddyfile中启用mercure指令并配置 JWT 密钥即可Laravel 侧通过mercure_publish()函数、file_get_contents()请求或第三方库发布更新。使用 Octane 时在config/octane.php中加入以下配置启用内置 Hub// config/octane.php // ... return [ // ... mercure [ anonymous true, publisher_jwt !ChangeThisMercureHubJWTSecretKey!, subscriber_jwt !ChangeThisMercureHubJWTSecretKey!, ], ];anonymous允许匿名订阅publisher_jwt与subscriber_jwt是 Hub 签发与校验 JWT 的密钥生产环境务必替换为高强度随机值。Mercure 支持的全部 Hub 配置指令都可以写进这个数组例如subscriptions订阅 API、cors_origins跨域等。发布与订阅更新时推荐使用 Laravel Mercure Broadcaster 库不引入额外依赖时也可以参照 docs/mercure.md 用纯 PHPmercure_publish()与原生 JavaScriptEventSource实现客户端订阅/.well-known/mercure?topic...端点服务端发布带 JWT 授权的 POST 请求。七、把 Octane 应用也打包成独立二进制Octane 应用同样可以打包为独立二进制。步骤是先按第三节完成 Octane 的安装配置再按第四节完成打包之后通过 Octane 以 Worker 模式启动 FrankenPHPPATH$PWD:$PATH frankenphp php-cli artisan octane:frankenphp[!CAUTION] 该命令要能工作独立二进制必须命名为frankenphp并且要出现在PATH中因此上面的命令把当前目录加入了PATH——Octane 启动时需要在路径里找到一个名为frankenphp的程序。这一步的原理可以追溯到 caddy/php-cli.go 的实现php-cli会把当前二进制的路径作为argv[0]传入 PHP CLI SAPI而 Octane 正是借助这一点找到当前正在执行的服务器程序来启动 Workerdocs/worker.md 也明确指出 Laravel Octane 就是 FrankenPHP Worker 模式在框架层的官方集成。小结从开发到生产再到分发FrankenPHP 为 Laravel 提供了四档可选的运行形态Docker 镜像一行命令即可起步本地独立二进制配合Caddyfile适合常规部署Laravel Octane 借助 Worker 模式让应用常驻内存、请求响应达到毫秒级而嵌入特性则能把整个应用压缩进单个静态二进制实现真正的应用即文件。配合内置的 Mercure Hub 与自动 HTTPSLaravel 应用可以在不引入额外基础设施的前提下同时获得高性能与实时能力。更多底层机制可继续阅读 docs/config.md、docs/worker.md、docs/embed.md 与 docs/mercure.md。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考