FrankenPHP独立二进制不可热替换，必须停服、清理残留进程与端口、覆盖旧版二进制、验证version及php--ini路径、清缓存并检查Caddyfile兼容性后重启。
不能直接“替换”二进制文件并期望服务无缝回退——FrankenPHP 的独立二进制自带 PHP 运行时、Caddy 和嵌入式配置，版本变更会直接影响 PHP 版本、扩展可用性、Caddy 行为及 FrankenPHP 内部 API 兼容性。必须停服、清理、验证、重启。
确认当前运行的是独立二进制而非 Docker 或系统包
FrankenPHP 官方只对独立二进制提供跨版本升级路径，Docker 镜像和系统包（如 apt）的更新逻辑完全不同。执行 which frankenphp 查看路径；若输出类似 /usr/local/bin/frankenphp 或项目目录下的 ./frankenphp，才是独立二进制。Docker 用户应改用 dunglas/frankenphp:tag 拉取旧镜像，不在此流程内。
停掉正在运行的 FrankenPHP 实例
FrankenPHP 没有热重载或平滑 reload 机制，强行覆盖二进制会导致进程僵死或监听端口残留。必须先终止所有相关进程：
- 执行
frankenphp stop（如果它支持且已注册为服务） - 否则用
pkill -f 'frankenphp.*server'或kill $(pgrep -f 'frankenphp.*server') - 再检查残留：
lsof -i :80 -i :443或ss -tulpn | grep ':80\|:443'，确保端口已释放 - 特别注意：如果之前启用了 Worker 模式，
frankenphp stop-workers也得先跑一遍，否则 worker 进程可能还在占资源
替换二进制并验证环境一致性
独立二进制不是纯可执行文件，它内部硬编码了 PHP 版本、扩展列表（如 mbstring、curl）、默认 Caddy 配置片段和 FrankenPHP 初始化逻辑。旧版本二进制可能不含你依赖的新扩展，或含已被移除的旧函数（比如 PHP 8.4 废弃的 create_function()）。操作要点：
立即学习“PHP免费学习笔记（深入）”；
- 从 GitHub Releases 页面 下载对应旧版本的静态二进制（如
frankenphp_1.2.0_linux_amd64.tar.gz），解压后覆盖原文件 - 执行
frankenphp version确认输出中显示目标版本号，且没有 panic 或 “PHP startup: Unable to load dynamic library” 类错误 - 检查
frankenphp php --ini输出的配置路径是否仍指向内置 php.ini；独立二进制通常不读取系统/etc/php，所以别去改那些路径 - 运行
frankenphp check（如有）或手动启动一次：frankenphp run --config ./Caddyfile，观察首行日志是Starting FrankenPHP Server还是报错
清理缓存与框架适配点
版本降级后最常被忽略的是缓存污染和框架隐式依赖：
- 清空 OPcache：
frankenphp opcache-reset（若支持），否则旧字节码可能被新 PHP 解释器误执行 - Laravel 用户需运行
php artisan config:clear && php artisan cache:clear && php artisan view:clear，尤其当旧 FrankenPHP 版本不支持某些 Octane 特性（如frankenphp_handle_request()签名变化）时，缓存里可能存着已失效的 worker 启动逻辑 - 检查
Caddyfile中是否用了仅在新版支持的指令，例如php_server { worker }在 1.1.x 之前根本不存在，降级后必须删掉，否则 frankenphp 启动失败但错误提示极不明显 - 如果你的应用曾调用过 FrankenPHP 特定的 Go-PHP 绑定函数（如
frankenphp_set_env()），请确认该函数在目标旧版本中是否已被导出——它在 1.0.x 和 1.2.x 之间有 ABI 变更
真正麻烦的从来不是下载哪个文件，而是 PHP 运行时和 FrankenPHP 控制层之间的耦合深度——它们打包在一起，就意味每次版本切换都是一次微型平台迁移。别跳过 frankenphp version 和首行启动日志验证，那是唯一能确认“你手里的二进制真的在按你想的方式跑”的依据。
