nginx如何自定义错误页面？如何改变状态码？

我们相信：世界是美好的，你是我也是。平行空间的世界里面，不同版本的生活也在继续...

nginx发出的各种状态码，苏南大叔个人觉得不能不信，也不能全信。有非200的状态码出现了，那就是有问题了。常见的代码里面，403/404/500。代码确实有明确意义，但是实际情况却和代码不符的情况，也不少见。本文描述的是：如何配置nginx的错误页面，如何人为更改状态码。

苏南大叔的"程序如此灵动"博客，记录苏南大叔的编程相关经验总结。本文测试环境：win10，nginx@1.15.11。

主要前提说明

如果本文的代码有所差异，请先理清思路：

• 本文的测试环境是win10。nginx在不同操作系统下的配置或表现，存在着较大的技术性差异。
• 本文配图中访问的资源都是普通静态资源。并非后端控制的资源（例如.php资源）。

特殊的页面状态码，并不适合本文的内容。如果按着标准格式写配置，不会报错，但是也不生效。这些特殊状态码包括：

• 401，鉴权性质的状态码。
• 301、302、307等跳转性质的状态码。

普通状态码错误页

下面以处理静态资源为例。配置一些常见的状态码的nginx配置。如下：

location / {
    index index.php index.html;
    error_page 404 /error/404.html;
    error_page 400 /error/400.html;
    error_page 403 /error/403.html;
    error_page 404 /error/404.html;
    error_page 500 /error/500.html;
    error_page 501 /error/501.html;
    error_page 502 /error/502.html;
    error_page 503 /error/503.html;
    error_page 504 /error/504.html;
    error_page 505 /error/505.html;
    error_page 506 /error/506.html;
    error_page 507 /error/507.html;
    error_page 509 /error/509.html;
    error_page 510 /error/510.html;
}

这段代码出自phpstudy里的nginx的vhost默认配置。

这里需要特殊说明的是：

• 上面这个配置适用的范围就是静态资源的范围（不包括类似php相关）。
• 特殊的状态码，写上虽然不报错，但是也不会生效。
• 相关的error/目录下的.html文件，都全部存在。

以404为例展开描述

配置了一堆状态码的错误页面，可以看出，仅仅是下面这句话的不断重复变种。

error_page 404 /error/404.html;

那么，就以这个最常见的404状态码展开讨论，看看它还有什么样的变形。

增加等号变200状态

error_page 404 = /error/404.html;

表面上看，就仅仅是增加了一个等号，实际效果上，状态码从404变成了200（404.html文件正常存在）。

等号变更状态码

这种情况下，新状态码更像是一个没有自主思想的傀儡。比如，下面的401代码，根本就没有弹框登陆效果。

error_page 404 =401 /error/404.html;

并且这种更改状态码的行为，写法上必须直接跟在等号的后面。

error_page 404 = 401 /error/404.html;  # 报错

否则报错：

nginx: [emerg] invalid value "="

可直接跳转到新网站

这个时候，相当于生效了一个跳转，在等号后面设置的新状态码（除非是个3字头的跳转码）并不会生效。比如：

error_page 404 http://test/ng.php;

如果要设置新的状态码的话（虽然不生效，强制为302代码），记得紧贴着等号，否则报错。

error_page 404 =500 http://test/ng.php;

这种设置下，无论如何设置，都会是两个请求，第一个大概率是个302，第二个大概率是个200。

关于301、302、303、307等跳转类代码的区别，可以参考：

• https://newsn.net/say/redirect-3xx.html

php下的后端状态码拦截

当对接php类似的后端代码，那么上述这些error_page设置的位置(location /{})，也不生效。需要配置在php的这个相关节点下[win系统]。例如：

location ~ \.php(.*)$ {
    fastcgi_pass   127.0.0.1:9001;
    fastcgi_index  index.php;
    fastcgi_split_path_info  ^((?U).+\.php)(/?.+)$;
    fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    fastcgi_param  PATH_INFO  $fastcgi_path_info;
    fastcgi_param  PATH_TRANSLATED  $document_root$fastcgi_path_info;
    include        fastcgi_params;
    error_page 403 /error/404.html;
    error_page 404 /error/404.html;
}

这里也有很多的情况分支，待到后续文章再描述。在本文里面，只需要知道：
location /{}里面的error_page控制不了location ~ \.php(.*)$ {}的状态码即可。或者说，当访问.php文件的时候，无视location /{}里面的error_page控制。

这些.php文件专属的error_page设置，并不会全部生效。一部分生效而已，大家可以自行尝试。

相关文章

• https://newsn.net/say/nginx-401.html
• https://newsn.net/say/nginx-403-selinux.html

结语

本文比较基础，在日常应用中，其实用的到的就仅仅是404页面的定制。不过，对于苏南大叔的后续文章来说，本文的作用是个话题引子。更多文章，请参考苏南大叔的系列文章：

• https://newsn.net/tag/nginx/
• https://newsn.net/tag/nginx/

如果本文对您有帮助，或者节约了您的时间，欢迎打赏瓶饮料，建立下友谊关系。
本博客不欢迎：各种镜像采集行为。请尊重原创文章内容，转载请保留作者链接。