指令参考

error_page

`error_page` 指令为指定的 HTTP 状态码配置自定义错误页面。 — NGINX HTTP Core

error_page
httpserverlocationif in location
语法error_page code1 [code2 ...] uri;
默认值none
上下文http, server, location, if in location
模块NGINX HTTP Core
参数2+

说明

`error_page` 指令用于 NGINX 配置中，为特定的 HTTP 状态码定义自定义错误响应。该指令可在不同上下文中使用，例如 `http`、`server`、`location`，或在 `location` 块内的 `if` 块中。你可以指定两个或更多参数：第一个是 HTTP 状态码或状态码范围（例如 `404` 或 `500 502 503 504`），第二个是作为错误页面的 URI，该 URI 可以指向静态文件或另一个 `location` 块。 当发生错误时，例如未找到文件（`404`）或服务器错误（`500`），NGINX 会检查为该状态码定义的 `error_page` 指令。如果找到匹配的错误码，NGINX 会返回所定义的 URI，从而为终端用户提供定制的响应。错误页面可以是磁盘上的文件，也可以是进一步处理请求的另一个 `location`。此外，它还可以包含内部重定向，以更优雅地处理复杂的错误响应。 `error_page` 的有效使用可以通过提供比服务器默认错误消息更具信息性或更美观的错误响应来提升用户体验。此外，开发者可以将自定义错误页面与针对特定错误码的更详细的分析或故障排除资源关联起来。这种灵活性有助于提高 Web 应用以及静态网站的可用性和故障排查效率。

配置示例

http {
    error_page 404 /custom_404.html;
    location = /custom_404.html {
        root /usr/share/nginx/html;
    }
}
⚠

指定不存在的 URI 可能导致递归的错误处理。

⚠

带有 `location` 块的错误页面本身不得返回 404，否则会触发下一个错误处理器。

⚠

并非所有 HTTP 状态码都可用；请务必查阅 NGINX 文档以获取可用的状态码。

相关指令

try_filesrewritelocation