Nginx错误拦截转发 error_page的问题解决

更新时间：2025年12月10日 11:11:38 作者：@菜菜_达

Nginx通过配置错误页面和请求处理机制,可以在请求失败时展示自定义错误页面,提升用户体验,下面就来介绍一下Nginx错误拦截转发 error_page的问题解决

在Nginx 中实现 “页面路径未请求成功之前展示错误页面”，核心是利用 Nginx 的错误页面配置和请求处理机制。通常，当请求的路径不存在（404 错误）或服务器处理失败（如 500 错误）时，Nginx 可以立即返回自定义错误页面。以下是具体实现步骤：

1. 准备自定义错误页面

首先，创建一个或多个自定义错误页面（如 404.html、500.html），放在 Nginx 可访问的目录下（例如/usr/share/nginx/html/errors/）。示例404.html内容：

<!DOCTYPE html>
<html>
<head>
    <title>页面未找到</title>
    <meta charset="utf-8">
</head>
<body>
    <h1>404 - 您请求的页面不存在</h1>
    <p>正在检查路径，请稍后重试...</p>
</body>
</html>

2. 配置 Nginx 错误页面

编辑 Nginx 配置文件（通常是/etc/nginx/nginx.conf或站点配置文件/etc/nginx/conf.d/your_site.conf），添加error_page指令，指定错误码对应的页面路径。

基础配置示例：

nginx.conf

server {
    listen 80;
    server_name your_domain.com;  # 替换为你的域名或IP

    # 网站根目录（根据实际情况修改）
    root /usr/share/nginx/html;
    index index.html index.htm;

    # 配置错误页面：当请求失败时返回对应页面
    # 404：路径不存在；500/502/503/504：服务器处理错误
    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/50x.html;

    # 确保错误页面的请求能被正确处理（避免错误页面本身404）
    location /errors/ {
        internal;  # 仅允许内部访问，不允许外部直接请求
        root /usr/share/nginx/html;  # 错误页面所在的根目录
    }

    # 其他常规配置（如静态文件处理等）
    location / {
        try_files $uri $uri/ =404;  # 尝试请求路径，不存在则返回404
        # 访问需登录的页面时，若未登录（401）或权限不足（403），返回错误页
        proxy_intercept_errors on;  # 开启后端错误拦截（关键！）
    }
}

注意：Nginx能处理的状态码有一定范围，v1.24.0版本的仅支持(300-599)，若配置完成后Nginx启动失败，可在安装包位置（\nginx-1.24.0\logs\error.log）的日志中查看失败原因。

3. 关键配置说明

error_page 404 /errors/404.html;：表示当发生 404 错误时，返回/errors/404.html页面。
internal;：限制错误页面只能被 Nginx 内部调用（避免用户直接访问/errors/404.html）。
try_files $uri $uri/ =404;：在location /中，Nginx 会先尝试访问请求的文件或目录，若都不存在则触发 404 错误，进而返回自定义页面。
proxy_intercept_errors on;默认情况下，Nginx 会直接将后端返回的 401/403 等错误码转发给客户端。开启该指令后，Nginx 会拦截后端返回的错误码，转而使用error_page配置的自定义页面，实现 “请求未完成（验证失败）时展示错误页”。
针对登录路径的精准拦截若只需对登录接口或需登录的页面生效，可在对应的location块中单独配置proxy_intercept_errors on;，避免全局拦截影响其他正常请求。

4. 生效配置

修改后重启 Nginx 使配置生效：

注意：在任务管理器中搜索nginx，关闭该任务后再重启方能生效。

# 检查配置是否有误
nginx -t

# 重启Nginx
start nginx  # 或 在安装包中找到nginx.exe 双击打开开

5.针对单个特定页面

如果你只想针对单个特定页面（例如 /user/profile）配置登录异常的错误页面，需要通过更精确的 location 匹配规则来实现。核心思路是：仅对目标页面的路径单独设置拦截规则，不影响其他页面。

1. 假设目标页面为/user/profile（个人资料页）

需要确保 Nginx 仅对访问 /user/profile 时的登录异常（401/403）返回自定义错误页，其他页面不受影响。

2. Nginx 配置示例

server {
    listen 80;
    server_name your_domain.com;

    root /usr/share/nginx/html;
    index index.html;

    # 定义登录异常的错误页面（全局可用，但仅被指定location触发）
    error_page 401 403 /errors/login-error.html;

    # 错误页面的内部访问配置（禁止外部直接访问）
    location /errors/ {
        internal;
        root /usr/share/nginx/html;
    }

    # 仅对单个页面 `/user/profile` 生效的配置
    location = /user/profile {  # 注意使用 `=` 精确匹配单个路径
        proxy_pass http://backend_server;  # 转发到后端服务
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # 关键：仅在此页面开启错误拦截，触发自定义错误页
        proxy_intercept_errors on;
    }

    # 其他页面的默认配置（不拦截错误，使用后端原生响应）
    location / {
        proxy_pass http://backend_server;
        proxy_set_header Host $host;
        # 这里不配置 proxy_intercept_errors，保持默认行为
    }
}

关键配置说明

location = /user/profile
- 使用 = 符号表示精确匹配，仅当请求路径完全等于 /user/profile 时才生效（不会匹配 /user/profile/123 等子路径）。
- 若需要匹配 /user/profile 及其子路径（如 /user/profile/avatar），可改用 location /user/profile（去掉 =）。
proxy_intercept_errors on; 仅在目标 location 中配置这样只有访问 /user/profile 时，后端返回的 401/403 错误才会被 Nginx 拦截，并返回自定义的 login-error.html；其他页面的错误会按默认逻辑处理（直接返回后端的原始错误响应）。
错误页面全局定义，但按需触发error_page 401 403 /errors/login-error.html 是全局定义的，但只有开启了 proxy_intercept_errors on; 的 location 才会实际使用该错误页，其他路径不影响。

注意：以上的配置需要后端小伙伴的积极配合，在转发到后端接口时，后端能够返回相应的状态码，因为Nginx 是反向代理服务器，主要擅长处理 HTTP 协议层的逻辑（如状态码、请求头、路径转发等），但对响应体中的业务字段（如 JSON 里的 success）处理能力有限（需要借助 ngx_http_lua_module 等模块编写脚本，复杂度高）。

通过以上配置，Nginx 会在请求路径未找到、服务器错误或超时等 “未成功” 场景下，立即展示自定义错误页面，提升用户体验。

到此这篇关于Nginx错误拦截转发 error_page的问题解决的文章就介绍到这了,更多相关Nginx错误拦截转发 error_page内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

Nginx配置文件解析与虚拟主机搭建过程
本文详细介绍了Nginx的配置文件和虚拟主机搭建,包括全局配置、I/O事件配置、HTTP与location配置,以及虚拟主机的三种搭建方式,通过实例操作,帮助读者理解和应用Nginx,实现高性能和安全的Web服务部署,感兴趣的朋友跟随小编一起看看吧
2025-12-12
Nginx geoip模块实现地区性负载均衡
相信做过awstats的都用过开源的geoip.dat ip数据库，刚好nginx wiki上有geoip 模块，这样就可以实现地区性的负载均衡，但是maxmind 的ip数据库对中国的支持不算太好，不过现在也不错了~
2010-12-12
nginx日志切割/分割之按天生成及定期删除日志
这篇文章主要给大家介绍了关于nginx日志切割/分割之按天生成及定期删除日志的相关资料,日志文件大会影响访问的速度和查找难度,文中给出了详细的代码示例,需要的朋友可以参考下
2023-08-08
Nginx内存不足对Web应用的影响及解决方法
本文详细介绍了Nginx内存不足对Web应用的影响,包括连接和请求处理失败、现有服务中断、性能严重下降、Nginx进程异常、触发操作系统OOMKiller、缓存失效和日志丢失或写入失败,文章还提供了诊断内存不足的监控工具和关键指标,需要的朋友可以参考下
2026-03-03
nginx关于add_header的坑及解决
这篇文章主要介绍了nginx关于add_header的坑及解决,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2023-12-12
解决Nginx + PHP（FastCGI）遇到的502 Bad Gateway错误
昨日，有朋友问我，他将Web服务器换成Nginx 0.6.31 + PHP 4.4.7（FastCGI）后，有时候访问会出现“502 Bad Gateway”错误，如何解决。
2009-10-10
Nginx之QPS限制模块的具体使用
本文主要介绍了Nginx之QPS限制模块的具体使用,主要介绍Nginx QPS限制模块的原理、安装和使用方法,具有一定的参考价值,感兴趣的可以了解一下
2023-09-09
nginx代理后端路径获取IP为127.0.0.1问题
文章讨论了在使用Nginx作为反向代理时,如何正确配置以避免在前端路径A/api访问后端时丢失真实的IP地址,通过有效的Nginx配置,可以确保在前后端分离的场景中,客户端通过前端路径访问后端时,后端能够正确获取客户端的真实IP地址,示例配置展示了如何实现这一目标
2025-02-02
详解Nginx配置WebSocket(支持wss与ws连接)
本文主要介绍了详解Nginx配置WebSocket(支持wss与ws连接),文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2025-09-09
Keepalived+Nginx双机配置小结
本文主要介绍了Keepalived+Nginx双机配置小结,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2025-03-03