知識庫 / Spring / Spring Boot RSS 訂閱

Spring Boot:自定義 Whitelabel 錯誤頁面

Spring Boot
HongKong
5
02:03 PM · Dec 06 ,2025

1. 概述

在本教程中,我們將學習如何禁用並自定義 Spring Boot 應用程序的默認錯誤頁面,適當的錯誤處理體現了專業性和高質量的工作。

2. 禁用白標錯誤頁面

首先,我們將通過將 server.error.whitelabel.enabled 屬性設置為 false 來完全禁用白標錯誤頁面:

server.error.whitelabel.enabled=false

將此條目添加到應用程序的 application.properties 文件中將禁用錯誤頁面,並顯示來自底層應用程序容器(例如 Tomcat)的簡潔頁面。

通過排除 ErrorMvcAutoConfiguration Bean,我們可以實現相同的結果。 我們可以通過在 properties 文件中添加以下條目來實現:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.ErrorMvcAutoConfiguration

#for Spring Boot 2.0
#spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

或者,我們可以將此註釋添加到主類中:

@EnableAutoConfiguration(exclude = {ErrorMvcAutoConfiguration.class})

以上所述的所有方法都會禁用白標錯誤頁面。這留下了一個問題:錯誤處理由誰來負責呢?

正如上面所説,通常是由底層應用程序容器來處理的。好消息是,我們可以通過顯示自定義錯誤頁面,而不是所有默認設置,進一步自定義這些內容。 這將是下一部分的主題。

3. 自定義錯誤頁面顯示

首先我們需要創建一個自定義 HTML 錯誤頁面。

我們將文件保存為 error.html 因為我們使用 Thymeleaf模板引擎:

<!DOCTYPE html>
<html>
<body>
<h1>Something went wrong! </h1>
<h2>Our Engineers are on it</h2>
<a href="/">Go Home</a>
</body>
</html>

如果將此文件保存在resources/templates目錄中,它將自動被Spring Boot默認的BasicErrorController所獲取

這正是我們顯示自定義錯誤頁所需的一切。通過一些樣式調整,我們現在將為我們的用户擁有一個外觀更漂亮的錯誤頁面:

 

我們還可以更具體,通過將文件命名為我們希望使用的HTTP狀態碼,例如,將文件保存為404.htmlresources/templates/error中,則它將被明確用於404錯誤。

3.1. 自定義錯誤控制器 (ErrorController)

目前限制在於無法在發生錯誤時運行自定義邏輯。為了實現這一點,我們需要創建一個錯誤控制器 Bean,它將替換默認的錯誤控制器。

為此,我們需要創建一個實現 ErrorController 接口的類。 此外,還需要將 server.error.path 屬性設置為自定義路徑,以便在發生錯誤時調用。

@Controller
public class MyErrorController implements ErrorController  {

    @RequestMapping("/error")
    public String handleError() {
        //do something like logging
        return "error";
    }
}

在上面的片段中,我們還使用 @Controller 註解了該類,併為指定的屬性 server.error.path 創建了映射。

server.error.path=/error

這樣控制器可以處理對/error路徑的調用。

handleError()中,我們將返回我們之前創建的自定義錯誤頁面。如果現在觸發404錯誤,則將顯示我們自定義的頁面。

讓我們進一步增強handleError()以顯示不同錯誤類型的自定義錯誤頁面。

例如,我們可以為404和500錯誤類型創建精心設計的頁面。然後,我們可以使用錯誤類型的HTTP狀態碼來確定要顯示的適當錯誤頁面。

@RequestMapping("/error")
public String handleError(HttpServletRequest request) {
    Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    
    if (status != null) {
        Integer statusCode = Integer.valueOf(status.toString());
    
        if(statusCode == HttpStatus.NOT_FOUND.value()) {
            return "error-404";
        }
        else if(statusCode == HttpStatus.INTERNAL_SERVER_ERROR.value()) {
            return "error-500";
        }
    }
    return "error";
}

對於404錯誤,例如,我們將看到 error-404.html 頁面:

4. 結論

憑藉這些信息,我們現在可以更優雅地處理錯誤,並向用户展示一個美觀的頁面。

user avatar
0 位用戶收藏了這個故事!
收藏

發佈 評論

Some HTML is okay.