使用 FrankenPHP 部署 WordPress从零安装、生产级 Caddyfile 到热重载完整指南【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp本文以 FrankenPHP 官方文档docs/es/wordpress.md英文版见 docs/wordpress.md为主体系统讲解如何在 WordPress 站点上启用 FrankenPHP先用php-server命令完成最小安装再通过Caddyfile搭建生产级配置自动 HTTPS、HTTP/3、Zstandard/Brotli/Gzip 压缩最后结合内置 Mercure 中心为 WordPress 主题接入热重载hot reload开发工作流。读完本文你将掌握一套可直接落地的 WordPress FrankenPHP 部署与开发方案。为什么用 FrankenPHP 运行 WordPressFrankenPHP 是一个基于 Caddy 构建的现代 PHP 应用服务器PHP 解释器直接内嵌于进程之中无需单独的 PHP-FPM 进程。将 WordPress 跑在 FrankenPHP 上可以获得一套现代、高性能的栈自动 HTTPS 证书签发与续期、HTTP/3 支持、Zstandardzstd压缩等均由 Caddy 与 FrankenPHP 原生产出。此外FrankenPHP 内置的 Mercure 中心与 hot reload 功能能让 WordPress 主题开发做到改完即刷新大幅提升开发体验。WordPress 最小安装一条命令跑起来官方文档给出的最小安装路径极其简单只需 5 步从 WordPress 官网下载 WordPress 安装包解压 ZIP 压缩包并在解压出的目录中打开终端执行启动命令frankenphp php-server浏览器访问http://localhost/wp-admin/按提示完成 WordPress 安装向导完成。php-server是 FrankenPHP 提供的一个开箱即用的生产级 PHP 服务器子命令其实现位于 caddy/php-server.go。从源码看cmdPHPServer函数该命令在底层做了这些事默认监听:80端口、将.php作为脚本扩展名、自动生成try_files回退规则优先匹配现有文件其次index.php最终回落到文件服务器并在启动时默认启用 zstd、br、gzip 三层压缩编码。也就是说这一条命令已经自带压缩、静态文件服务与 PHP 执行能力适合快速演示与开发。php-server还支持若干有用参数均见 caddy/php-server.go 的 flag 定义参数简写作用--domain-d指定域名启用 HTTPS 并切换到 443 端口--root-r指定站点根目录--listen-l自定义监听地址--worker-w指定 worker 脚本可重复--watch无监视文件变化常与 hot reload 搭配--access-log-a启用访问日志--debug-v输出详细调试日志--mercure-m启用内置 Mercure 中心--no-compress无关闭 zstd、br、gzip 压缩例如本地用 HTTPS 域名方式启动frankenphp php-server --domainexample.com此时默认监听端口会切换到 443 并使用 HTTPS源码中通过certmagic.HTTPSPort实现。生产级配置用frankenphp run配合 Caddyfile最小安装适合演示若要用于生产官方文档推荐使用frankenphp run配合一个Caddyfile。以下配置来自 docs/es/wordpress.md与英文版 docs/wordpress.md 一致example.com php_server encode zstd br gzip log逐行拆解example.com站点地址。FrankenPHP 会为该域名自动签发并维护 HTTPS 证书同时监听 443 端口支持 HTTP/3只要域名的 A/AAAA 记录指向服务器即可php_serverCaddy 指令作用等价于先尝试匹配 PHP 文件其余交给静态文件服务是大多数应用的最佳选择若需要完全掌控可改用底层php指令详见 docs/config.md 的php_server/php指令说明encode zstd br gzip开启响应压缩编码优先级为 Zstandard → Brotli → Gzip浏览器支持哪种就协商哪种log开启访问日志便于生产排障。php_server指令的常用子选项php_server是 Caddyfile 站点块中的高级指令支持多种子选项完整列表见 docs/config.md。与 WordPress 部署最相关的几个example.com root public/ # 显式指定站点根目录WordPress 推荐将根目录指到 wp 源码目录 php_server { root public/ # 与上方等价可写在这里 env WP_ENV production # 为 PHP 注入环境变量 request_body_timeout 60s # 请求体读超时默认 60s0 表示禁用 # worker { # worker 模式按需开启见下文 # file index.php # } }注意FrankenPHP 默认会为所有主机名包括localhost自动启用 HTTPS。如果开发环境想关闭可在启动时设置SERVER_NAME环境变量为http://或:80详见 docs/config.md 的Disabling HTTPS一节。此外官方仓库还提供了一个带注释的完整 Caddyfile 模板caddy/frankenphp/Caddyfile其中包含了 Mercure 的注释配置与SERVER_NAME、SERVER_ROOT、FRANKENPHP_CONFIG等便捷环境变量可直接作为生产起点。进阶WordPress 与 worker 模式若你的 WordPress 站点启用了任意插件或自定义代码把 PHP 常驻内存worker 模式请阅读 docs/worker.md。worker 模式让应用只启动一次之后请求处理只需数毫秒但代价是代码改动不会即时生效——这正是下文 hot reload 要解决的核心痛点之一。为 WordPress 启用热重载Hot ReloadHot reload 是 FrankenPHP 面向开发环境的招牌功能当工作目录中的 PHP、模板、JS、CSS 等文件发生变化时浏览器无需手动刷新即可实时更新页面工作流类似前端工具链中的 HMRHot Module Replacement。官方明确指出该功能原生兼容 WordPress、Laravel、Symfony 以及任何其他 PHP 应用或框架见 docs/hot-reload.md。其工作链路如下详见 docs/hot-reload.md 的How FrankenPHP hot reload works一节FrankenPHP 底层基于e-dant/watcher库监视文件系统变化caddy/hotreload.go中定义了默认监视模式文件变化时将变更文件列表封装为 JSON 推送到内置的 Mercure 中心浏览器端的 JS 库订阅 Mercure 事件若页面加载了 Idiomorph 库则对 DOM 进行 morph保留滚动位置与输入状态否则执行整页刷新。第一步在 Caddyfile 中开启 Mercure 与 hot_reload热重载依赖内置的 Mercure 中心来推送事件因此在 Caddyfile 中需要同时启用 Mercure 与hot_reload子指令配置示例来自 docs/es/wordpress.mdlocalhost mercure { anonymous } php_server { hot_reload }mercure { anonymous }启用内置 Mercure 中心anonymous允许无 JWT 的匿名订阅者浏览器端订阅事件不需要鉴权php_server { hot_reload }在php_server指令下挂上hot_reload子指令。从源码看caddy/hotreload.goconfigureHotReload会做两件事把监视目录与 Mercure hub 通过frankenphp.WithHotReload()注入 PHP 线程选项同时向每个请求注入名为FRANKENPHP_HOT_RELOAD的环境变量其值形如/.well-known/mercure?topictopic供 PHP 侧读取订阅地址。若未配置 Mercure 就开启hot_reloadFrankenPHP 会直接报错unable to enable hot reloading: no Mercure hub configured。默认情况下FrankenPHP 会监视当前工作目录下匹配以下 glob 模式的所有文件./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}也可以显式指定要监视的文件/目录支持 glob 语法php_server { hot_reload src/**/*{.php,.js} config/**/*.yaml }或使用长格式自定义 Mercure topic 与多个监视路径php_server { hot_reload { topic hot-reload-topic watch src/**/*.php watch assets/**/*.{ts,json} watch templates/ watch public/css/ } }[!WARNING] hot reload仅适用于开发环境。官方文档明确警告该功能会暴露敏感的内部细节并拖慢应用切勿在生产环境开启见 docs/hot-reload.md。第二步在主题的 functions.php 中注入客户端脚本WordPress 服务端检测到文件变化后浏览器还需要订阅事件才能完成页面更新。官方文档给出的做法是在主题的functions.php中通过wp_head动作注入两段 JS代码来自 docs/es/wordpress.md// wp-content/themes/your-theme/functions.php function hot_reload() { ? ?php if (isset($_SERVER[FRANKENPHP_HOT_RELOAD])): ? meta namefrankenphp-hot-reload:url content?$_SERVER[FRANKENPHP_HOT_RELOAD]? script srchttps://cdn.jsdelivr.net/npm/idiomorph/script script srchttps://cdn.jsdelivr.net/npm/frankenphp-hot-reload/esm typemodule/script ?php endif ? ?php } add_action(wp_head, hot_reload);关键点说明$_SERVER[FRANKENPHP_HOT_RELOAD]由 FrankenPHP 注入的环境变量见 caddy/hotreload.go内容为 Mercure 订阅地址。isset()判断保证未开启 hot reload 时页面零额外开销meta namefrankenphp-hot-reload:url ...把订阅地址暴露给前端库idiomorphDOM morphing 库加载后热更新会保留滚动位置与输入状态而不是粗暴整页刷新frankenphp-hot-reload/esm官方提供的前端库自动订阅 Mercure 中心、后台拉取最新页面内容并完成 DOM 更新。第三步启动一切就绪后在 WordPress 根目录执行frankenphp runfrankenphp run会读取当前目录下的Caddyfile并启动 CaddyFrankenPHP 默认在启动目录查找Caddyfile也可用-c指定路径。此后无论是修改主题的functions.php、模板文件还是 CSS浏览器都会自动刷新或 morph 更新。进阶技巧保留特定 DOM 节点个别场景如 Symfony Web Debug 工具条等开发工具希望某些节点不被 morph 替换可给对应元素加上data-frankenphp-hot-reload-preserve属性见 docs/hot-reload.md。与 worker 模式组合如果你的 WordPress 应用开启了 worker 模式PHP 常驻内存意味着改代码后 worker 不会自动重启。此时应同时配置worker { watch }让 worker 随文件变化重启与hot_reload形成浏览器刷新 worker 重启的完整开发闭环示例见 docs/hot-reload.md。手动实现客户端逻辑不想引入官方 JS 库时也可用原生EventSource直接订阅 Mercure 中心事件订阅路径为/.well-known/mercure?topic...完整的订阅与发布示例见 docs/mercure.md。小结围绕 WordPress 这个具体场景FrankenPHP 给出了从一条命令启动到生产级 Caddyfile再到开发期热重载的完整路径快速上手frankenphp php-server一条命令即可访问wp-admin完成安装生产部署frankenphp runCaddyfile自动 HTTPS、HTTP/3、zstd/br/gzip 压缩一站式解决开发体验mercure { anonymous }php_server { hot_reload } 主题functions.php注入脚本改完即所见保留页面状态。如需深入了解热重载的完整工作原理与全部配置项可继续阅读 docs/hot-reload.md、docs/mercure.md 与 docs/config.md对应实现源码位于 caddy/hotreload.go 与 caddy/php-server.go。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考