nginx配置未生效的根本原因是配置文件未被加载，常见于Docker中default.conf优先拦截、include路径错误或COPY失败；需用nginx -T验证是否含location ~ .php$块，并检查fastcgi_pass、SCRIPT_FILENAME及root作用域一致性。
nginx -T 显示的不是你的 app.conf
根本问题往往不是配置写错了，而是根本没加载——nginx -T 输出里压根看不到你写的 location ~ \.php$ 块。常见原因有：
• 你的 app.conf 被复制到了 /etc/nginx/conf.d/，但镜像自带的 default.conf 还在，且按字母序先被加载，它用 server { listen 80; } 拦下了所有请求
• include 路径写错，比如写成 include /etc/nginx/conf.d/*.conf; 却漏了分号，或路径不存在
• Docker 构建时 COPY 失败（如源文件路径错、Dockerfile 执行目录不对），实际容器里根本没有你的配置文件
验证方式：进容器执行 nginx -T | grep -A 5 "location.*\.php"，没输出就说明配置没生效
fastcgi_pass 地址不匹配 PHP-FPM 实际监听位置
fastcgi_pass 写成 127.0.0.1:9000 却让 PHP-FPM 监听 Unix socket（如 /run/php/php8.1-fpm.sock），或者反过来，都会导致 502。关键要看两边是否对齐：
• 查 PHP-FPM 配置：看 www.conf 里的 listen = 行，是 127.0.0.1:9000 还是 /run/php/php8.1-fpm.sock
• Nginx 配置里 fastcgi_pass 必须严格一致，不能混用 IP+端口 和 socket 路径
• Docker 场景下还要确认 socket 文件路径是否挂载正确，比如 /run/php/ 目录在容器内是否存在、权限是否为 www-data:www-data
SCRIPT_FILENAME 指向错误的物理路径
即使 fastcgi_pass 通了，PHP-FPM 也可能会报 “File not found”，因为 SCRIPT_FILENAME 拼出来的路径根本不存在。典型错误：
• 写成 $document_root$fastcgi_script_name，但 $document_root 是 /var/www/html，而 PHP 文件实际在 /app/public
• 没用 $realpath_root，遇到符号链接时解析失败
• 在子目录部署（如 http://example.com/app/）却没调整 root 或 alias，导致 $document_root 指向错误层级
推荐写法：fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;，并确保 root 指令在 server 块顶层，不在 location 里
index.php 不在 index 指令里，或 location / 里缺 try_files
访问 http://localhost/ 只显示 Nginx 欢迎页，不是 index.php，说明两个地方漏了：
• index 指令没包含 index.php：必须写成 index index.php index.html;，否则 Nginx 默认只找 index.html
• Laravel/ThinkPHP 这类框架依赖前端控制器，location / 块里没加 try_files $uri $uri/ /index.php?$query_string;，导致 /user/profile 这种路由直接 404，根本进不了 PHP
注意：try_files 必须放在 location / 里，不能只靠 location ~ \.php$ —— 后者只管 .php 文件，不管伪静态路由
立即学习“PHP免费学习笔记（深入）”；
最常被忽略的是配置加载顺序和 root 作用域——写在 location 块里的 root 会覆盖 server 级的值，导致 $document_root 计算错误；而 Docker 场景下默认配置残留比本地环境更隐蔽。
