Nginx错误拦截转发 error_page

[1. 准备自定义错误页面](#1. 准备自定义错误页面)

[2. 配置 Nginx 错误页面](#2. 配置 Nginx 错误页面)

基础配置示例：

[3. 关键配置说明](#3. 关键配置说明)

[4. 生效配置](#4. 生效配置)

5.针对单个特定页面

[1. 假设目标页面为 /user/profile（个人资料页）](#1. 假设目标页面为 /user/profile（个人资料页）)

[2. Nginx 配置示例](#2. Nginx 配置示例)

关键配置说明

需求：页面未请求成功，需要展示错误的页面，避免卡死提升用户体验感。

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

1. 准备自定义错误页面

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

html

预览

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

javascript 复制代码

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，关闭该任务后再重启方能生效。

javascript 复制代码

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

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

5.针对单个特定页面

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

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

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

2. Nginx 配置示例

nginx

javascript 复制代码

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 会在请求路径未找到、服务器错误或超时等 "未成功" 场景下，立即展示自定义错误页面，提升用户体验。