Piwigo Docker环境下Nginx未返回404却下载PHP文件问题排查

API 探路者

2026-8-1

解决Piwigo Docker镜像的404异常问题

问题回顾

访问不存在的页面时出现两种异常：

访问/fakepage.html或/fakepage时，PHP文件被直接下载而非解析
访问/fakepage.php时，页面左上角显示“File not found”但HTTP状态码为200
所有本该返回404的请求，日志均记录为200，且跨多个宿主机系统都存在该问题。

解决方向及具体操作

1. 修复Nginx的PHP处理逻辑

当前Nginx配置缺少关键的FastCGI参数，导致PHP文件无法正确解析，同时未检查文件是否存在。修改location ~ ^(.+\.php)(.*)$块：

location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include /etc/nginx/fastcgi_params;
    # 强制指定脚本路径，确保FastCGI正确识别PHP文件
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    # 先检查PHP文件是否存在，不存在直接返回404
    try_files $fastcgi_script_name =404;
}

2. 优化try_files路由规则

原规则把所有不存在的请求都转发到index.php，导致静态请求被错误处理。拆分路由逻辑：

location / {
    try_files $uri $uri/ @piwigo_router;
}

# 单独处理Piwigo的动态路由
location @piwigo_router {
    rewrite ^ /index.php$is_args$args;
}

这样静态资源请求优先匹配，只有动态路由才转发到index.php，避免静态请求触发PHP解析。

3. 让Piwigo返回正确的404状态码

Piwigo的index.php在处理无效页面时，没有发送404 HTTP头，导致日志显示200。找到index.php中include(PHPWG_ROOT_PATH.'include/section_init.inc.php');这一行，之后添加：

// 检测无效页面，返回404状态码
if (empty($page['body']) || isset($page['error'])) {
    http_response_code(404);
    // 如果有自定义404页面，可替换为include对应文件
    echo '<h1>404 Not Found</h1>';
    exit;
}