如何解决 Docker 中 Nginx 无法正确代理 PHP-FPM 的问题

2026-01-15

如何解决 Docker 中 Nginx 无法正确代理 PHP-FPM 的问题

本文详解 docker compose 下 nginx + php-fpm 协同部署 laravel 应用时，php 文件不执行、仅显示默认欢迎页的典型故障原因及修复方案，核心在于 nginx 配置文件覆盖与加载优先级。

在使用 nginx:stable-alpine 和 php:8.1-fpm-alpine 构建 Laravel 开发环境时，一个高频但隐蔽的问题是：Nginx 容器启动后始终返回 “Welcome to nginx!” 默认页面，而 index.php（如）完全未被解析执行。即使容器正常运行、文件路径挂载正确、PHP-FPM 监听 9000 端口、且 fastcgi_pass php:9000 配置无误——问题根源往往不在网络或权限，而在于 Nginx 配置加载顺序与文件命名冲突。

? 根本原因：default.conf 优先级高于自定义配置

Alpine 版 Nginx 镜像默认在 /etc/nginx/conf.d/ 目录下内置了 default.conf 文件。该文件定义了一个监听 80 端口的 server 块，内容即为显示欢迎页的静态服务：

server {
    listen       80;
    server_name  localhost;
    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }
    # ... 其他日志等
}

而你的 docker/nginx/conf.d/app.conf 虽然被 COPY 到同一目录，但由于 Nginx 按字母序加载 conf.d/*.conf，且 default.conf 始终存在，它会与你的 app.conf 同时生效。当请求 http://localhost:8888/ 时，若未匹配到 server_name laravel.local（浏览器实际访问的是 localhost），Nginx 将回退至第一个匹配的 server 块——即 default.conf 中的默认服务，导致 PHP 完全不参与处理。

✅ 正确解决方案：覆盖或移除默认配置

✅ 方案一（推荐）：直接覆盖 default.conf

修改 Dockerfile 中的 COPY 指令，将自定义配置强制写入 default.conf：

立即学习“PHP免费学习笔记（深入）”；

微信 WeLM

WeLM不是一个直接的对话机器人，而是一个补全用户输入信息的生成模型。

下载

# docker/nginx/Dockerfile
FROM nginx:stable-alpine
COPY docker/nginx/conf.d/app.conf /etc/nginx/conf.d/default.conf  # ← 关键：覆盖默认配置
WORKDIR /var/www/html
COPY ./src/public /var/www/html/public

✅ 优势：简洁、确定性强，无需额外清理步骤。

✅ 方案二：显式删除默认配置

在 Dockerfile 中增加删除命令（需注意 Alpine 的 rm 语法）：

FROM nginx:stable-alpine
COPY docker/nginx/conf.d/app.conf /etc/nginx/conf.d/app.conf
RUN rm -f /etc/nginx/conf.d/default.conf  # ← 移除干扰项
WORKDIR /var/www/html
COPY ./src/public /var/www/html/public

✅ 方案三（进阶）：使用 include + 独立主配置

在 Dockerfile 中替换整个 nginx.conf，确保 conf.d/ 只加载你的配置：

FROM nginx:stable-alpine
COPY docker/nginx/nginx.conf /etc/nginx/nginx.conf
COPY docker/nginx/conf.d/app.conf /etc/nginx/conf.d/app.conf
WORKDIR /var/www/html
COPY ./src/public /var/www/html/public

其中 nginx.conf 需明确指定：

# docker/nginx/nginx.conf
user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events { worker_connections  1024; }

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    log_format    main  '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$http_x_forwarded_for"';
    access_log    /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    # ? 关键：只包含你的配置，不加载 default.conf
    include /etc/nginx/conf.d/app.conf;
}

⚠️ 补充注意事项

server_name 不影响本地测试：你配置了 server_name laravel.local，但浏览器访问 localhost:8888 时不会匹配。临时调试建议改为 server_name localhost; 或直接删掉该行（Nginx 会以第一个 server 为默认）。
PHP-FPM 监听方式：当前 fastcgi_pass php:9000 使用 TCP，确保 PHP 容器中 php-fpm.conf 未改写监听地址（默认 0.0.0.0:9000 即可）。生产环境更推荐 Unix Socket（如 fastcgi_pass unix:/var/run/php/php-fpm.sock;），性能更高且更安全。
文件挂载一致性：你同时挂载了 ./src/public（Nginx）和 ./src（PHP），需确保 public/ 是 Laravel 的 Web 入口目录，且 index.php 中的 require __DIR__.’/../vendor/autoload.php’; 路径在 PHP 容器内可解析（因 ./src 挂载到 /var/www/html，public 在其子目录，路径是正确的）。

✅ 验证步骤

修改 Dockerfile 并重建镜像：

docker-compose down && docker-compose up --build -d

进入 Nginx 容器确认配置已生效：

docker-compose exec server cat /etc/nginx/conf.d/default.conf
# 应输出你的 app.conf 内容，且无 default.conf 原始内容

检查 Nginx 配置语法：

docker-compose exec server nginx -t
# 输出应为 "syntax is ok", "test is successful"

浏览器访问 http://localhost:8888 —— 此时应显示 phpinfo() 页面。

通过精准控制 Nginx 配置加载逻辑，即可彻底解决 PHP-FPM 不被调用的问题。记住：在容器化环境中，“约定优于配置”常被打破，显式覆盖才是可靠实践。

https://www.php.cn/faq/1986265.html