macOS上FrankenPHP v1.3端口冲突需先用lsof -P -n -i :8000查残留进程（如frankenphp、php、messenger:consume），kill -15 PID清理；若无输出则sudo lsof -iTCP -sTCP:LISTEN | grep :8000排查系统级占用；启动时必须用--addr :8080指定新端口并绑定0.0.0.0，不可省略冒号或误写为8080。
在macOS上运行FrankenPHP v1.3时，若默认的:8000端口已被占用（比如被旧进程、Laravel内置服务器或AirPlay服务抢占），必须主动指定新端口才能启动成功；否则会卡在bind: address already in use错误，且无法自动降级或跳过。
查清当前端口占用情况
打开终端，执行：lsof -P -n -i :8000。如果输出中COMMAND列显示frankenphp、php或messenger:consume，说明是残留进程占着——记下PID，下一步用kill -15 PID终止它。若无输出但启动仍失败，立刻补查：sudo lsof -iTCP -sTCP:LISTEN | grep :8000，这能揪出kernel_task等系统级监听者，比如macOS ControlCenter有时会静默占用:7000这类端口。
启动时用--addr参数覆盖默认端口
FrankenPHP v1.3的php-server子命令支持--addr选项，这是最直接、无需改环境变量的方式。例如想换到:8080，就运行：frankenphp php-server --document-root public --addr :8080。这一步操作起来很简单，直接把命令里的:8000替换成你要的新端口就行。注意：冒号不能漏，:8080是合法格式，8080则会被当作路径解析导致报错。
【必须绑定0.0.0.0而非localhost】 如果你加了--host localhost，外部curl会失败——macOS的localhost解析可能走IPv6或环回别名，而FrankenPHP实际只监听了127.0.0.1。正确写法是--host 0.0.0.0，确保所有网卡都能接入。验证是否生效：启动后立刻执行lsof -i :8080，输出里LISTEN状态那一行的ADDR列必须含0.0.0.0:8080，不是127.0.0.1:8080。
立即学习“PHP免费学习笔记（深入）”；
用SERVER_NAME环境变量强制HTTP监听（备选）
方法一：docker run场景下设-e SERVER_NAME=:8080。此方式仅适用于容器部署，且必须同步配-p 8080:8080，否则宿主机根本收不到包。SERVER_NAME=:8080的作用不是“设置端口”，而是关闭Caddy的HTTPS自动流程，让整个服务退化为纯HTTP模式——如果你本就想用反向代理或CDN终结TLS，这反而是更干净的选择。
方法二：本地二进制直跑时设SERVER_NAME=:8080 frankenphp php-server --document-root public。这种方式绕过--addr，靠环境变量驱动，适合CI脚本或需要统一配置的场景。但要注意：它对php-server有效，对frankenphp-worker无效——后者必须用--addr单独指定。
提示：SERVER_NAME值里绝不能带http://、/path或域名前缀，SERVER_NAME=http://localhost:8080或SERVER_NAME=example.com:8080都会被Caddy忽略，回落到默认:8000。
