FrankenPHP跑Symfony怎么优雅发布让用户无感-php教程-PHP中文网

frankenphp 运行 symfony 实现无感发布的关键是启用 worker 模式（frankenphp_worker=1）并正确配置 php_worker 指向 public/index.php 绝对路径，配合 stop-workers 命令滚动更新。

frankenphp跑symfony怎么优雅发布让用户无感

FrankenPHP 跑 Symfony 时，发布无感的关键不在“重启服务”，而在绕过进程重启带来的请求中断——它本身不支持传统信号平滑 reload，但能靠 worker 模式 + 部署策略实现真正零停机。

默认的 FrankenPHP 普通模式（即没开 worker）每次改代码都要手动 kill 进程再启动，必然中断请求。真正的无感发布依赖其内置的 worker 生命周期管理：

FRANKENPHP_WORKER=1 必须设为环境变量，不是可选项；否则 frankenphp-worker 启动后只是个孤立 CLI 进程，和 Caddy 主进程不联动
worker 启动入口必须是 Symfony 的 public/index.php，不是 bin/console 或其他脚本；FrankenPHP 会自动复用这个入口做 autoload 和容器初始化
不要在 Caddyfile 里写 php_worker 后直接跟 exec php public/index.php —— 这样起的是 shell 子进程，FrankenPHP 无法接管生命周期，热更失败

FrankenPHP 的 php_worker 指令不是转发器，而是告诉内嵌 PHP 运行时：“下次请求来时，别重新加载整个框架，复用这个已初始化的 worker 实例”。配置错路径会导致 worker 根本不生效：

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

路径必须指向 public/index.php，且是相对于 Caddy 工作目录的绝对路径，例如 /var/www/myapp/public/index.php
不能写成 ./public/index.php 或 public/index.php —— Caddy 启动时 pwd 不一定等于项目根，worker 会找不到文件直接静默退出
如果用了自定义 APP_ENV，记得在 Caddyfile 里显式传： php_worker /var/www/myapp/public/index.php { env APP_ENV=prod }
别漏掉 max_requests：设为 1000 或 5000，避免单 worker 累积内存泄漏；FrankenPHP 会在达到后自动 fork 新 worker，旧 worker 处理完手上请求再退出

FrankenPHP 不监听 SIGHUP，但提供了 frankenphp stop-workers 命令配合 max_requests 实现可控滚动更新：

新版本代码部署到新目录（如 /var/www/myapp/releases/20261004-123456），软链 current 指向它
确保新代码的 public/index.php 可读、var/cache 可写、composer install --no-dev --optimize-autoloader 已执行
执行 frankenphp stop-workers —— 它不会杀主进程，只通知所有活跃 worker 在完成当前请求后退出；新请求会由新 worker 接管（自动加载新代码）
别用 systemctl restart frankenphp：这会强制中断所有连接，HTTP/2 流直接 reset，前端可能报 net::ERR_CONNECTION_RESET

Symfony 的 assets:install 和 cache:warmup 在 worker 模式下行为和 FPM 不同：

cache:warmup 必须在新 release 目录下执行，且要加 --env=prod；worker 启动时只 warmup 当前 APP_ENV 对应的 cache，旧环境 cache 不影响
静态资源（CSS/JS）建议走 assets:install --symlink，而非复制；这样软链一换，Nginx/Caddy 下次读的就是新文件，不用清浏览器缓存
如果用了 Encore，构建产物必须放在 public/build/ 下，且 Caddy 的 root 必须指向 public，否则 php_worker 找不到入口，file_get_contents(/build/manifest.json) 会失败