监听地址重复会导致frankenphp启动失败，因配置中存在两个及以上完全相同的server.listen_address（来自frankenphp.yaml、include文件、cli参数或环境变量），进程会报“address already in use”并退出；需用frankenphp config dump检查最终生效配置，结合--debug日志定位重复绑定点。
监听地址重复会导致 FrankenPHP 启动失败
FrankenPHP 一旦在 frankenphp.yaml（或通过环境变量、CLI 参数）中配置了两个及以上完全相同的 server.listen_address，进程会直接退出，并报错类似 address already in use 或更明确的 duplicate listen address。它不会静默覆盖或跳过——这是好事，但错误信息有时不够直白，尤其当监听地址来自多处（如主配置 + include 文件 + CLI 参数）时。
检查所有可能注入监听地址的位置
FrankenPHP 的监听地址可来自多个源头，必须逐个排查：
-
frankenphp.yaml根级的server.listen_address（最常见） - 任意被
include进来的 YAML 文件（比如include: ["./servers/*.yaml"]），其中某一个文件也定义了server.listen_address - CLI 启动时显式传入的
--listen参数（例如frankenphp run --listen :8080） - 环境变量
FRANKENPHP_LISTEN_ADDRESS（优先级高于配置文件）
注意：如果同时存在 server.listen_address 和 servers 数组（多 server 模式），后者每个 server 项里的 listen_address 也各自独立参与去重校验——即不能有两个 servers 用相同地址。
用 frankenphp config dump 快速验证最终生效配置
这个命令会合并所有来源（文件、环境变量、CLI 参数），输出最终解析后的完整配置，是排查重复最可靠的手段：
frankenphp config dump | grep -A 5 "listen_address"
重点关注输出中是否出现多个 listen_address 字段值完全一致的情况。特别留意：
- 值为
:80和0.0.0.0:80在底层视为相同地址（都绑定到所有 IPv4 接口） -
[::]:80（IPv6）和:80默认不冲突，但如果系统启用了 IPv6 dual-stack，:80实际也会监听 IPv6，此时与[::]:80就构成重复 - Unix socket 路径如
unix:/var/run/frankenphp.sock也算监听地址，同样不可重复
启动时加 --debug 看更详细的地址绑定日志
运行 frankenphp run --debug，启动过程中会打印每一条监听地址的绑定尝试，例如：
DEBUG binding to address ":8080" DEBUG binding to address "127.0.0.1:8080" FATAL failed to start server: listen tcp :8080: bind: address already in use
从日志里能清晰看到它先绑了一次，再绑第二次时失败——说明配置里确实写了两次。如果没看到重复的 binding to address 行，那问题可能出在外部（比如另一个进程占用了端口），而不是配置重复。
真正容易被忽略的是 include 路径匹配到多个文件、且每个文件都写了 server.listen_address；或者环境变量和配置文件同时设置了，而你只盯着 YAML 看。动手前先跑一遍 config dump，比猜快得多。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
