本文详解 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免费学习笔记（深入）”；
# 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 不被调用的问题。记住：在容器化环境中，“约定优于配置”常被打破，显式覆盖才是可靠实践。
