FrankenPHP启动时端口被占需显式指定--addr，如--addr :8001或--addr 127.0.0.1:8001，避免使用:3000/:8000/:8080等易冲突端口，并确保frankenphp.yaml/toml中server.address与命令行一致。
frankenphp serve 启动时怎么改 --addr
默认不加参数时，frankenphp serve 会监听 :8000（开发模式），但若该端口被占，它直接失败，不提示谁在用。必须显式指定新地址：
- 命令行启动：加
--addr :8001或更明确的--addr 127.0.0.1:8001，后者只响应本机请求，更安全 - 避免用
:3000、:8000、:8080这类高频端口，容易和 Node.js、Laravel Sail、Docker Compose 默认配置撞车 - 如果项目里有
frankenphp.yaml或frankenphp.toml，确保其中server.address值与命令行一致，否则配置可能被忽略（尤其当SERVER_NAME环境变量存在时）
Docker 容器里 SERVER_NAME 和 -p 映射必须对齐
容器内监听端口不由 --port 控制，而是由 SERVER_NAME 环境变量决定。错配会导致 curl 通但 PHP 拿不到正确 Host 或 HTTPS 状态：
-
SERVER_NAME=:8080→ 容器内监听:8080，对应docker run -p 8080:8080 -
SERVER_NAME=:80→ 容器内监听:80，对应docker run -p 8080:80（此时访问http://localhost:8080，但 PHP 中$_SERVER['HTTP_HOST']是localhost:8080，可能破坏 URL 生成逻辑） - 若同时挂载了
Caddyfile或frankenphp.toml，只要设了SERVER_NAME，它们的监听配置就失效——这是设计行为，不是 bug
查端口占用不能只信控制台报错
报错 address already in use 只说明 bind 失败，但不等于“别人在用”。常见干扰项包括：
- 上一个
frankenphp-worker没彻底退出（Linux/macOS 用ps aux | grep frankenphp，Windows 用tasklist | findstr frankenphp） - Windows 下 PID = 4（HTTP.sys 驱动），不能
taskkill，得进services.msc停W3SVC和Web Deployment Agent Service - macOS 用
lsof -P -n -i :8080，别用netstat——它不显示 PID - Linux 用
ss -tuln | grep ':8080'，看pid/program列，确认是caddy、nginx还是残留的frankenphp
共存场景下让 FrankenPHP 当纯 worker 更稳
如果你已有 Caddy/Nginx 在跑，别让它俩抢 :80/:443。把 FrankenPHP 当 FastCGI 后端，由现有反向代理转发请求：
立即学习“PHP免费学习笔记（深入）”；
- 启动 FrankenPHP：加
--frankenphp-worker-address 127.0.0.1:8081（注意不是--addr） - Caddyfile 里删掉原有
php_server插件，改用reverse_proxy http://127.0.0.1:8081 - 必须加
header_up X-Forwarded-Proto {scheme}，否则 PHP 里$_SERVER['HTTPS']为空 - FrankenPHP 不再监听公网端口，冲突概率归零，也符合它“PHP 运行时”的定位
真正麻烦的不是换端口，而是换完后前端代码或框架配置还硬写 http://localhost；环境变量、APP_URL、Caddy 的 header_up 缺一不可。
