快捷導(dǎo)航

Nginx錯誤攔截轉(zhuǎn)發(fā) error_page的問題解決

更新時間：2025年12月10日 11:11:38 作者：@菜菜_達(dá)

Nginx通過配置錯誤頁面和請求處理機(jī)制,可以在請求失敗時展示自定義錯誤頁面,提升用戶體驗(yàn),下面就來介紹一下Nginx錯誤攔截轉(zhuǎn)發(fā) error_page的問題解決

在Nginx 中實(shí)現(xiàn) “頁面路徑未請求成功之前展示錯誤頁面”，核心是利用 Nginx 的錯誤頁面配置和請求處理機(jī)制。通常，當(dāng)請求的路徑不存在（404 錯誤）或服務(wù)器處理失敗（如 500 錯誤）時，Nginx 可以立即返回自定義錯誤頁面。以下是具體實(shí)現(xiàn)步驟：

1. 準(zhǔn)備自定義錯誤頁面

首先，創(chuàng)建一個或多個自定義錯誤頁面（如 404.html、500.html），放在 Nginx 可訪問的目錄下（例如/usr/share/nginx/html/errors/）。示例404.html內(nèi)容：

<!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或站點(diǎn)配置文件/etc/nginx/conf.d/your_site.conf），添加error_page指令，指定錯誤碼對應(yīng)的頁面路徑。

基礎(chǔ)配置示例：

nginx.conf

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

    # 網(wǎng)站根目錄（根據(jù)實(shí)際情況修改）
    root /usr/share/nginx/html;
    index index.html index.htm;

    # 配置錯誤頁面：當(dāng)請求失敗時返回對應(yīng)頁面
    # 404：路徑不存在；500/502/503/504：服務(wù)器處理錯誤
    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/50x.html;

    # 確保錯誤頁面的請求能被正確處理（避免錯誤頁面本身404）
    location /errors/ {
        internal;  # 僅允許內(nèi)部訪問，不允許外部直接請求
        root /usr/share/nginx/html;  # 錯誤頁面所在的根目錄
    }

    # 其他常規(guī)配置（如靜態(tài)文件處理等）
    location / {
        try_files $uri $uri/ =404;  # 嘗試請求路徑，不存在則返回404
        # 訪問需登錄的頁面時，若未登錄（401）或權(quán)限不足（403），返回錯誤頁
        proxy_intercept_errors on;  # 開啟后端錯誤攔截（關(guān)鍵?。?
    }
}

注意：Nginx能處理的狀態(tài)碼有一定范圍，v1.24.0版本的僅支持(300-599)，若配置完成后Nginx啟動失敗，可在安裝包位置（\nginx-1.24.0\logs\error.log）的日志中查看失敗原因。

3. 關(guān)鍵配置說明

error_page 404 /errors/404.html;：表示當(dāng)發(fā)生 404 錯誤時，返回/errors/404.html頁面。
internal;：限制錯誤頁面只能被 Nginx 內(nèi)部調(diào)用（避免用戶直接訪問/errors/404.html）。
try_files $uri $uri/ =404;：在location /中，Nginx 會先嘗試訪問請求的文件或目錄，若都不存在則觸發(fā) 404 錯誤，進(jìn)而返回自定義頁面。
proxy_intercept_errors on;默認(rèn)情況下，Nginx 會直接將后端返回的 401/403 等錯誤碼轉(zhuǎn)發(fā)給客戶端。開啟該指令后，Nginx 會攔截后端返回的錯誤碼，轉(zhuǎn)而使用error_page配置的自定義頁面，實(shí)現(xiàn) “請求未完成（驗(yàn)證失?。r展示錯誤頁”。
針對登錄路徑的精準(zhǔn)攔截若只需對登錄接口或需登錄的頁面生效，可在對應(yīng)的location塊中單獨(dú)配置proxy_intercept_errors on;，避免全局?jǐn)r截影響其他正常請求。

4. 生效配置

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

注意：在任務(wù)管理器中搜索nginx，關(guān)閉該任務(wù)后再重啟方能生效。

# 檢查配置是否有誤
nginx -t

# 重啟Nginx
start nginx  # 或 在安裝包中找到nginx.exe 雙擊打開開

5.針對單個特定頁面

如果你只想針對單個特定頁面（例如 /user/profile）配置登錄異常的錯誤頁面，需要通過更精確的 location 匹配規(guī)則來實(shí)現(xiàn)。核心思路是：僅對目標(biāo)頁面的路徑單獨(dú)設(shè)置攔截規(guī)則，不影響其他頁面。

1. 假設(shè)目標(biāo)頁面為/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觸發(fā)）
    error_page 401 403 /errors/login-error.html;

    # 錯誤頁面的內(nèi)部訪問配置（禁止外部直接訪問）
    location /errors/ {
        internal;
        root /usr/share/nginx/html;
    }

    # 僅對單個頁面 `/user/profile` 生效的配置
    location = /user/profile {  # 注意使用 `=` 精確匹配單個路徑
        proxy_pass http://backend_server;  # 轉(zhuǎn)發(fā)到后端服務(wù)
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # 關(guān)鍵：僅在此頁面開啟錯誤攔截，觸發(fā)自定義錯誤頁
        proxy_intercept_errors on;
    }

    # 其他頁面的默認(rèn)配置（不攔截錯誤，使用后端原生響應(yīng)）
    location / {
        proxy_pass http://backend_server;
        proxy_set_header Host $host;
        # 這里不配置 proxy_intercept_errors，保持默認(rèn)行為
    }
}

關(guān)鍵配置說明

location = /user/profile
- 使用 = 符號表示精確匹配，僅當(dāng)請求路徑完全等于 /user/profile 時才生效（不會匹配 /user/profile/123 等子路徑）。
- 若需要匹配 /user/profile 及其子路徑（如 /user/profile/avatar），可改用 location /user/profile（去掉 =）。
proxy_intercept_errors on; 僅在目標(biāo) location 中配置這樣只有訪問 /user/profile 時，后端返回的 401/403 錯誤才會被 Nginx 攔截，并返回自定義的 login-error.html；其他頁面的錯誤會按默認(rèn)邏輯處理（直接返回后端的原始錯誤響應(yīng)）。
錯誤頁面全局定義，但按需觸發(fā)error_page 401 403 /errors/login-error.html 是全局定義的，但只有開啟了 proxy_intercept_errors on; 的 location 才會實(shí)際使用該錯誤頁，其他路徑不影響。

注意：以上的配置需要后端小伙伴的積極配合，在轉(zhuǎn)發(fā)到后端接口時，后端能夠返回相應(yīng)的狀態(tài)碼，因?yàn)镹ginx 是反向代理服務(wù)器，主要擅長處理 HTTP 協(xié)議層的邏輯（如狀態(tài)碼、請求頭、路徑轉(zhuǎn)發(fā)等），但對響應(yīng)體中的業(yè)務(wù)字段（如 JSON 里的 success）處理能力有限（需要借助 ngx_http_lua_module 等模塊編寫腳本，復(fù)雜度高）。

通過以上配置，Nginx 會在請求路徑未找到、服務(wù)器錯誤或超時等 “未成功” 場景下，立即展示自定義錯誤頁面，提升用戶體驗(yàn)。

到此這篇關(guān)于Nginx錯誤攔截轉(zhuǎn)發(fā) error_page的問題解決的文章就介紹到這了,更多相關(guān)Nginx錯誤攔截轉(zhuǎn)發(fā) error_page內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: