需先确认安装方式：Homebrew用户执行brew uninstall frankenphp、清理残留后tap dunglas/frankenphp并install；Go构建用户必须go clean -modcache再go install github.com/dunglas/frankenphp/cmd/frankenphp@v1.4.0，最后清理端口与socket并验证health接口返回v1.4.0。
在 macOS 上将 FrankenPHP 从 v1.2.1 升级到 v1.4 最新版本，需避开 Homebrew 默认安装路径残留、Go 模块缓存污染、旧二进制未清理导致的端口/Socket 冲突等典型陷阱，否则新版本启动时会报 bind: address already in use 或静默加载旧版本。
确认当前安装方式与版本来源
打开终端，执行：frankenphp version → 查看输出中 【Built with】 字段：若含 go mod 路径或 github.com/dunglas/frankenphp 提交哈希，则为 Go 直接构建版；若显示 homebrew 或路径含 /opt/homebrew/，则是 Homebrew 安装。二者升级路径完全不同，混用会导致 【二进制与配置文件版本错配】，后续所有操作都无效。
再运行 which frankenphp，记录返回路径（如 /opt/homebrew/bin/frankenphp 或 /usr/local/bin/frankenphp），后续替换必须精准覆盖该位置。
Homebrew 安装用户：强制重装最新稳定版
FrankenPHP 的 Homebrew tap 已于 2026 年 8 月迁移到官方仓库，旧 shivammathur/php 或第三方 tap 不再提供 v1.4 支持。
立即学习“PHP免费学习笔记（深入）”；
第一步：卸载旧版并清理残留
执行 brew uninstall frankenphp → 然后手动删除可能残留的配置目录：rm -rf ~/.frankenphp 和 /usr/local/etc/frankenphp.yaml（若存在）。
第二步：拉取最新官方源并安装brew tap dunglas/frankenphp → brew install frankenphp。这一步会自动下载 v1.4.0（截至 2026-10-15 的最新稳定版），无需指定版本号。
第三步：验证安装结果
运行 frankenphp version，确认输出中 Version: 行显示 v1.4.0，且 Built with: 含 go1.23 及之后版本 —— 若仍显示 go1.21，说明本地 Go 缓存未更新，需执行 brew cleanup && brew update 后重试安装。
Go 构建用户：用 go install 替换二进制
此方法适用于你曾用 go install github.com/dunglas/frankenphp/cmd/frankenphp@latest 安装的用户，v1.4 引入了新的信号处理逻辑，必须用 go install 覆盖，不能仅复制二进制文件。
方法一：直接升级（推荐）
执行 go install github.com/dunglas/frankenphp/cmd/frankenphp@v1.4.0。Go 会自动下载模块、编译并覆盖 $GOPATH/bin/frankenphp 中的旧二进制。
方法二：清除缓存后重建（解决“升级后仍运行旧版”问题）
先运行 go clean -modcache → 再执行 go install github.com/dunglas/frankenphp/cmd/frankenphp@v1.4.0。这一步必须做，因为 v1.2.1 的模块缓存可能被 v1.4.0 的依赖图错误复用，导致编译出的二进制实际仍是旧逻辑。
注意：【不要用 go get 替代 go install】 —— go get 在 Go 1.22+ 已弃用，且不会触发重新编译，只会更新 go.mod，极易造成“版本号更新但二进制未变”的假象。
升级后必须执行的验证与清理
升级完成后立即检查端口与 Socket 文件状态，避免新旧实例共存：
运行 lsof -P -n -i :8080（将 8080 替换为你实际使用的端口）→ 若输出中仍有 frankenphp 进程，用 kill -15 PID 终止它；再执行 ls -l /tmp/frankenphp.sock → 若文件存在且修改时间早于当前升级时间，手动删除：rm /tmp/frankenphp.sock。
最后启动服务：frankenphp serve --addr :8080 → 立即访问 http://localhost:8080/health，返回 HTTP 200 且 body 含 "version":"v1.4.0" 即为成功。
