FrankenPHP下Symfony的Xdebug断点怎么调-php教程-PHP中文网

frankenphp 下 xdebug 断点失效主因是 cli 模式默认禁用调试，必须显式配置 xdebug.mode=debug 和 xdebug.start_with_request=yes，并确保 phpstorm 监听端口（9003）与 xdebug.client_port 一致、ide key 匹配。

frankenphp下symfony的xdebug断点怎么调

FrankenPHP 本身不接管 Xdebug 的通信链路，断点调试是否生效，完全取决于 PHP 进程是否加载了 Xdebug 扩展、xdebug.mode 是否启用 debug、以及 IDE（如 PHPStorm）能否通过 DBGP 协议连上它——而 FrankenPHP 的特殊之处在于：它用 Go 启动 PHP Worker，且默认以 CLI 模式运行 PHP 脚本，**不是传统 FPM 的 CGI 模式**。这意味着很多“照搬 Nginx+PHP-FPM 调试配置”的做法会失效。

FrankenPHP 启动时 PHP 是 CLI 模式，Xdebug 必须显式启用 debug 模式

FrankenPHP 默认调用的是 php -S 或自定义 Worker 入口，走的是 CLI SAPI。Xdebug 3 在 CLI 下默认关闭调试（xdebug.mode=off），即使扩展已加载，php -v 显示 Xdebug，断点也完全不触发。

xdebug.mode 必须显式设为 debug（不是 develop 或 off）
CLI 下不读取 $_SERVER['HTTP_XDEBUG_SESSION_START'] 等 Web 触发头，所以不能靠浏览器插件或 URL 参数激活
必须配合 xdebug.start_with_request=yes 或 xdebug.trigger_value=1 + 手动触发（但 CLI 下更推荐前者）

示例 php.ini 片段：

[XDebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

Symfony App 在 FrankenPHP 中要走 Worker 模式，而非 public/index.php 直接暴露

FrankenPHP 推荐用 frankenphp-worker 运行 Symfony，即把 public/index.php 当作 Worker 入口。此时 PHP 进程常驻，Xdebug 连接只需建立一次；但如果误配成 “静态文件服务 + index.php CGI 转发”，就退化为每次请求新建 CLI 进程，Xdebug 可能来不及握手就退出。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

确认 frankenphp.yaml 中启用了 worker：

workers:
  - name: "symfony"
    script: "public/index.php"

不要在 routes 里把 / 直接映射到 public/index.php —— 那是 CGI 行为，Xdebug 不稳定
启动命令必须带 --worker：frankenphp serve --worker，否则不加载 Worker 模式
CLI 环境变量会被继承，可在启动前加：XDEBUG_CONFIG="idekey=PHPSTORM" frankenphp serve --worker

PHPStorm 连接失败？重点检查 client_port 和 idekey 是否匹配

FrankenPHP 下的 PHP 进程是 CLI，它不会自动从 HTTP 请求中提取 IDE key，必须靠环境变量或配置固化。PHPStorm 默认监听 9003，而很多老教程还写 9000，端口不一致直接导致连接超时静默失败。

PHPStorm 设置路径：Preferences > Languages & Frameworks > PHP > Debug > DBGp Proxy，Port 填 9003，IDE Key 填 PHPSTORM
确保 xdebug.client_port=9003 与之严格一致（xdebug.client_host 保持 127.0.0.1 即可）
xdebug.idekey 可省略，但若设置了就必须和 PHPStorm 的 IDE Key 完全一致（大小写敏感）
临时验证连接：启动 FrankenPHP 后，在另一终端执行 nc -zv 127.0.0.1 9003，通则说明 PHPStorm 已监听；不通则检查 PHPStorm 是否启用了 DBGp Proxy

最易被忽略的一点：FrankenPHP 的 Worker 进程启动后，首次 HTTP 请求才会真正触发 PHP 执行并尝试连接 Xdebug；此前没有任何日志、无报错、断点也不亮——你得先发个请求（比如 curl http://localhost:8080/），再看 /tmp/xdebug.log 是否出现 Connecting to configured address。没这句，说明 Xdebug 根本没试图拨号，问题一定出在 xdebug.mode 或 start_with_request 上。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！