FrankenPHP 运行 Laravel 应用完整指南：Docker、Octane 与独立可执行文件部署

FrankenPHP 运行 Laravel 应用完整指南Docker、Octane 与独立可执行文件部署【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphpFrankenPHP 是现代的 PHP 应用服务器基于 Caddy 构建内置 PHP 解释器可直接服务 PHP 文件、支持 worker 常驻内存模式并可将 PHP 应用打包为自包含的静态可执行文件。本篇指南以 docs/tr/laravel.md 为核心系统讲解三种主流的 Laravel 部署路径用官方 Docker 镜像快速启动、用独立二进制在本地运行、以及把 Laravel 应用含 Octane 模式编译成单一可执行文件交付。读完本文你将掌握 Laravel FrankenPHP 从开发到生产的完整配置与打包技能。一、使用 Docker 镜像快速运行 Laravel官方 Docker 镜像dunglas/frankenphp开箱即用运行一个 Laravel 应用只需把项目挂载到镜像的/app目录。在 Laravel 应用根目录执行docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp端口映射的含义80:80HTTP 流量443:443HTTPS 流量FrankenPHP 默认对localhost等主机名自动签发证书详见 config.md443:443/udpHTTP/3QUIC流量-v $PWD:/app将当前 Laravel 项目目录挂载到容器内/appFrankenPHP 会直接从/app/public提供服务容器内置了一份默认 Caddyfile其站点块默认root {$SERVER_ROOT:public/}即把/app/public作为 Web 根目录并通过php_server指令执行 PHP、encode zstd br gzip开启压缩——这与 Laravel 的标准目录结构完全吻合因此挂载后即可直接访问。开发环境下建议追加--tty参数以获得人类可读的彩色日志默认输出为 JSON 格式日志若希望自定义镜像安装额外 PHP 扩展如pdo_mysql、intl、zip、opcache或通过FRANKENPHP_CONFIG环境变量默认启用 worker 模式等可参考 docker.md 中关于install-php-extensions、xcaddy和 Docker Compose 卷挂载的说明。二、本地安装使用独立二进制运行 Laravel如果不使用 Docker也可以下载对应系统的 FrankenPHP 独立二进制在本地直接运行 Laravel 项目下载与系统对应的二进制文件参见 README.md 中 standalone binary 部分在 Laravel 项目根目录创建Caddyfile写入以下配置{ frankenphp } # 你的服务器域名 localhost { # 将 Web 根目录设置为 public/ 目录 root public/ # 启用压缩可选 encode zstd br gzip # 从 public/ 目录执行 PHP 文件并服务静态资源 php_server { try_files {path} index.php } }在 Laravel 项目根目录启动frankenphp run逐行解读这份配置frankenphp全局选项启用 FrankenPHP 模块root public/把站点根目录指向 Laravel 的public/避免源码泄露到 Web 层encode zstd br gzip依次启用 Zstandard、Brotli、Gzip 三种压缩编码Caddy 会根据客户端协商自动选择php_server是 FrankenPHP 的核心指令它先尝试按try_files规则匹配此处为{path}与index.php的回退再通过内部php指令执行 PHP 文件最后由内置file_server服务静态资源。php_server的展开逻辑可在 config.md 中看到等价的路由写法try_files {path} index.php是 Laravel 前端控制器的关键所有不存在的路径最终都会落到public/index.php由 Laravel 路由接管。php_server指令还支持root、env、split_path、request_body_timeout、file_server off以及块级worker等子选项完整清单见 config.md。三、集成 Laravel Octaneworker 常驻内存模式Laravel Octane 是 Laravel 官方的高性能服务器编排层而 FrankenPHP 是 Octane 官方支持的服务器之一。在 worker 模式下PHP 进程只在启动时引导一次应用之后常驻内存处理请求避免了每次请求都重新引导框架的开销响应时间可降至毫秒级原理详见 worker.md。安装与启动composer require laravel/octane安装后运行octane:install将 Octane 配置文件发布到应用中并指定 FrankenPHP 作为服务器php artisan octane:install --serverfrankenphp通过 Artisan 命令启动 Octane 服务器php artisan octane:frankenphpoctane:frankenphp可用选项octane:frankenphp命令接受以下选项选项说明默认值--host服务器绑定的 IP 地址127.0.0.1--port服务器监听端口8000--admin-port管理服务器Caddy admin API监听端口2019--workers处理请求的 worker 数量auto自动探测--max-requests服务器重启前每个 worker 处理的最大请求数500--caddyfileFrankenPHPCaddyfile文件路径Octane 内置的模板Caddyfile--https启用 HTTPS、HTTP/2 与 HTTP/3并自动生成、续期证书关闭--http-redirect将 HTTP 请求重定向到 HTTPS仅在同时传入--https时生效关闭--watch应用文件变更时自动重载服务器关闭--poll监听时使用文件系统轮询适用于网络文件系统关闭--log-level使用本地 Caddy 日志记录指定级别及以上的消息—提示若希望获得结构化的 JSON 日志接入日志分析平台时很有用请显式传入--log-level选项。几点深层说明--max-requests与 FrankenPHP 的max_requests机制对应PHP 并非为长驻进程设计不少库和遗留代码会缓慢泄漏内存因此让 worker 处理一定数量请求后自动重启是务实的缓解手段相关配置见 config.md 与 worker.md--watch基于 FrankenPHP 的文件监听能力未指定具体路径时默认监听./**/*.{env,php,twig,yaml,yml}常与热重载搭配使用详见 config.md--caddyfile默认指向 Octane 自带的模板开发者可替换为自定义Caddyfile以进一步控制php_server、worker 数量或全局选项。四、将 Laravel 应用打包为独立可执行文件借助 FrankenPHP 的应用嵌入功能详见 docs/embed.md可以将 Laravel 应用与 PHP 解释器、Caddy Web 服务器一起编译进单个静态可执行文件。这样交付的应用不需要目标机器安装 PHP、Composer 或任何运行时依赖。编写static-build.Dockerfile在应用仓库根目录创建static-build.DockerfileFROM --platformlinux/amd64 dunglas/frankenphp:static-builder-gnu # 若打算在 musl-libc 系统如 Alpine上运行二进制改用 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警告部分.dockerignore文件会忽略vendor/目录和.env文件。构建前请务必检查并相应调整或删除.dockerignore否则编译产物会缺少依赖与配置。构建与导出二进制构建镜像docker build -t static-laravel-app -f static-build.Dockerfile .将二进制从镜像中导出到宿主机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-tmpEMBEDdist/app/环境变量指示构建脚本将dist/app/下的源码与资源嵌入二进制构建脚本build-static.sh会依据应用的composer.json自动编译所需 PHP 扩展生成的dist/frankenphp-linux-x86_64即自包含可执行文件。初始化并启动应用导出二进制后依次执行 Laravel 的初始化步骤所有命令都通过二进制的php-cli子命令运行 PHP其底层实现在 cli.go 中通过frankenphp_execute_script_cli在嵌入的 PHP 解释器中执行脚本# 填充各类缓存 frankenphp php-cli artisan optimize # 执行数据库迁移如有 frankenphp php-cli artisan migrate # 生成应用密钥 frankenphp php-cli artisan key:generate # 启动 Web 服务器 frankenphp php-server应用至此即可对外提供服务。php-server是 FrankenPHP 内置的生产级命令实现在 caddy/php-server.go默认以当前目录为根目录、自动启用 HTTPS 并监听 80/443 端口它还支持--domain、--root、--listen、--worker、--watch、--mercure、--no-compress等标志适合快速部署、演示与开发场景。调整存储路径Laravel 默认将上传文件、缓存、日志等存放在应用目录的storage/下。对嵌入型应用而言这并不合适——因为每次发布新版本应用会被解包到不同的临时目录storage/数据会随之丢失。解决方法设置LARAVEL_STORAGE_PATH环境变量例如写入.env或在引导代码中调用Illuminate\Foundation\Application::useStoragePath()把存储目录指向临时目录之外的持久化位置。在独立可执行文件中运行 Octane甚至可以先把 Octane 正确安装见上文第三节再按上一节步骤打包然后以 worker 模式启动PATH$PWD:$PATH frankenphp php-cli artisan octane:frankenphp警告该命令要求独立二进制必须命名为frankenphp——Octane 会在PATH中查找名为frankenphp的程序因此需要通过PATH$PWD:$PATH将二进制所在目录加入搜索路径。五、总结三种部署方式覆盖了 Laravel 应用的不同生命周期Docker一条docker run命令即可挂载运行最适合开发与快速验证独立二进制 本地 Caddyfile无需容器即可运行配置直观适合本地开发与演示静态可执行文件把应用、PHP 解释器与 Caddy 融为一体交付物单一、无需任何运行时配合LARAVEL_STORAGE_PATH和 Octane worker 模式可满足生产环境对可移植性与性能的要求。无论选择哪条路径php_server指令、worker 常驻内存机制、Caddyfile全局配置与php-cli/php-server子命令都是理解与驾驭 FrankenPHP Laravel 组合的关键。进一步可阅读 docs/config.md 掌握全部配置项或参考 docs/worker.md 深入 worker 模式的超全局变量行为与状态持久化细节。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考