如何为Nginx配置全局PHP错误页面（含多虚拟主机场景）

一、单服务器场景的修正配置 #

原配置问题分析 #

你当前的配置存在3个核心问题，导致测试无效：

1. PHP处理块的try_files直接将不存在的PHP文件转发到/index.php，跳过了Nginx的错误码触发逻辑，error_page规则无法生效。
2. location = /index.php添加了internal指令，但原配置中try_files是直接外部访问该路径，会被Nginx拒绝。
3. 仅指定了404错误的处理规则，未覆盖你需要的其他HTTP错误码。

正确单服务器配置 #

# 静态资源处理：不存在则返回对应错误码，触发error_page规则
location / {
    try_files $uri $uri/ =404;
}

# PHP文件处理：先检查文件是否存在，不存在直接返回404
location ~ \.php$ {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_pass unix:/opt/homebrew/var/run/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

# 覆盖所有需要处理的HTTP错误码，指向统一的错误处理文件
error_page 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 421 422 423 424 425 426 428 429 431 451 500 501 502 503 504 505 506 507 508 510 511 /error.php;

# 错误处理PHP的专属配置，传递错误信息给PHP
location = /error.php {
    include fastcgi_params;
    fastcgi_pass unix:/opt/homebrew/var/run/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    # 传递错误码和请求路径到PHP，用于页面展示
    fastcgi_param STATUS_CODE $status;
    fastcgi_param REQUEST_URI $request_uri;
}

配套PHP示例（error.php） #

你可以在error.php中根据传递的参数展示对应错误页面：

<?php
$statusCode = $_SERVER['STATUS_CODE'] ?? 500;
$errorMap = [
    404 => '页面未找到',
    403 => '访问被禁止',
    500 => '服务器内部错误',
    400 => '无效请求',
    503 => '服务器维护中'
];
$errorMsg = $errorMap[$statusCode] ?? '未知错误';
?>
<!DOCTYPE html>
<html>
<head>
    <title><?= $statusCode ?> - <?= $errorMsg ?></title>
</head>
<body>
    <div style="text-align: center; margin-top: 100px;">
        <h1><?= $statusCode ?></h1>
        <p><?= $errorMsg ?></p>
        <p>请求路径：<?= $_SERVER['REQUEST_URI'] ?></p>
    </div>
</body>
</html>

二、多虚拟主机场景的全局配置方案 #

针对10-20台虚拟主机，无需重复编写配置，可通过Nginx的全局包含功能实现统一管理：

1. 创建全局错误处理配置文件 #

新建文件/opt/homebrew/etc/nginx/conf.d/global-error.conf（路径根据你的Nginx安装位置调整），内容如下：

# 全局错误码映射规则
error_page 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 421 422 423 424 425 426 428 429 431 451 500 501 502 503 504 505 506 507 508 510 511 /global-error.php;

# 全局错误页面的PHP处理（所有虚拟主机共用同一份error.php）
location = /global-error.php {
    include fastcgi_params;
    fastcgi_pass unix:/opt/homebrew/var/run/php-fpm.sock;
    # 指定全局错误页面的绝对路径，无需每个虚拟主机单独放置
    fastcgi_param SCRIPT_FILENAME /usr/local/share/nginx/error-pages/error.php;
    fastcgi_param STATUS_CODE $status;
    fastcgi_param REQUEST_URI $request_uri;
}

# 全局PHP文件处理规则
location ~ \.php$ {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_pass unix:/opt/homebrew/var/run/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

2. 在虚拟主机中引入全局配置 #

每个虚拟主机的server块只需保留专属配置（如域名、根目录、SSL），并引入全局错误配置：

server {
    listen 443 ssl;
    server_name mysite.bla;
    root /path/to/mysite/public;
    index index.php index.html;

    # 此处添加你的SSL证书配置...

    # 引入全局错误处理规则
    include /opt/homebrew/etc/nginx/conf.d/global-error.conf;

    # 虚拟主机专属静态资源处理
    location / {
        try_files $uri $uri/ =404;
    }
}

3. 统一部署全局错误页面 #

将error.php放置在/usr/local/share/nginx/error-pages/目录下，确保PHP-FPM的运行用户拥有该文件的读取权限。

最后验证步骤 #

每次修改配置后，执行以下命令确保配置有效：

nginx -t

验证通过后重启Nginx：

nginx -s reload

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