Docker化PHP应用（含Xdebug）无法访问问题排查与最佳实践

问题排查与修复 #

1. Nginx与PHP服务连接失败 #

你的Nginx配置中fastcgi_pass app:9000;，但docker-compose里PHP服务的名称是php，不是app。Nginx无法解析app这个服务名，导致PHP请求无法转发。

修复：
修改docker/nginx/default.conf中的fastcgi_pass为PHP服务名称：

fastcgi_pass php:9000;

2. Nginx根目录与挂载路径不匹配 #

docker-compose中Nginx的volume配置是./:/var/www，但Nginx配置的root是/var/www/html——这意味着容器内的/var/www/html是空目录，你的项目文件（包括index.php）被挂载到了/var/www，Nginx找不到入口文件。

修复：
调整docker-compose中Nginx的volume，将项目根目录挂载到/var/www/html：

webserver:
  image: nginx:latest
  ports:
    - "8080:80"
  volumes:
    - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    - ./:/var/www/html  # 修改为对应Nginx根目录的路径

3. 优化Xdebug配置（避免端口冲突） #

Xdebug 3默认使用9003端口，和PHP-FPM的9000端口不冲突，建议补充端口配置确保调试正常：
修改docker/php/conf.d/xdebug.ini：

zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.client_port=9003  # 添加此行明确端口

4. 重启服务验证 #

执行以下命令重新构建并启动服务：

docker-compose down
docker-compose up --build

之后访问http://127.0.0.1:8080即可正常加载页面。

最佳实践 #

• 服务名称统一：docker-compose中的服务名称必须和Nginx等依赖服务的引用名称一致，避免DNS解析失败。
• 挂载路径对齐：Web服务器（Nginx）和PHP服务的项目挂载路径要保持一致，防止文件找不到的问题。
• Xdebug版本适配：Xdebug 3和2的配置参数差异极大，PHP 7.4兼容Xdebug 3，建议指定具体版本安装，避免兼容性问题：

  FROM php:7.4-fpm
  
  RUN pecl install xdebug-3.1.6 \
      && docker-php-ext-enable xdebug
  

• 日志排查优先：遇到访问问题时，先查看容器日志定位原因：

  # 查看Nginx日志
  docker-compose logs webserver
  # 查看PHP-FPM日志
  docker-compose logs php
  

内容的提问来源于stack exchange，提问作者sina