Django 的 handler404：自定義 404 錯誤頁面的核心

更新日期： 2025 年 1 月 1 日

在 Django 應用中，handler404 是一個特殊的路由變數，用於處理所有未匹配路徑的請求。

通過自定義 handler404，我們可以返回結構化的 JSON 數據或渲染友好的 HTML 錯誤頁，適配 API 和普通瀏覽器請求。

本文將介紹 handler404 的核心概念、配置方式以及測試方法，幫助你全面掌握 Django 的 404 錯誤處理。

什麼是 handler404？

• 定義：
  handler404 是 Django 中專門用來處理 HTTP 404 錯誤的路由變數。
  
  當用戶請求的 URL 無法在 urlpatterns 中找到匹配時，Django 會自動調用 handler404 指定的函數。
• 作用：
  • 自定義錯誤頁的內容。
  • 支援不同的響應類型（例如 JSON 或 HTML）。
  • 提升用戶體驗和開發靈活性。

如何配置 handler404？

編寫自定義 404 處理函數

handler404 函數的簽名必須包含兩個參數：request 和 exception。

以下是一個同時支援 JSON 和 HTML 返回的自定義函數：

from django.http import JsonResponse  
from django.shortcuts import render  

def custom_404_view(request, exception):  
    if "application/json" in request.headers.get("Accept", ""):  
        return JsonResponse({  
            "error": "Page not found",  
            "status_code": 404,  
            "detail": "The requested URL was not found on this server."  
        }, status=404)  
    else:  
        return render(request, "404.html", status=404)  

在主路由中設置 handler404

在 Django 的主路由文件 urls.py 中，將 handler404 指向自定義函數。

from core.views import custom_404_view  

# 配置自定義的 404 錯誤處理  
handler404 = custom_404_view  

注意：

• handler404 不需要顯式添加到 urlpatterns 中，Django 會在找不到匹配路由時自動執行該函數。
• 此配置適用於所有應用的未匹配路徑。

handler404 的工作原理

1. 路由匹配機制：
   • 當用戶發送一個請求時，Django 會依次檢查 urlpatterns 中的路徑是否與請求的 URL 匹配。
   • 如果找到匹配的路徑，執行對應的視圖函數；如果無匹配，觸發 404 錯誤。
2. 調用 handler404：
   • Django 會將請求傳遞給 handler404 中配置的函數。
   • 該函數根據請求頭（Accept）判斷是否返回 JSON 或渲染 HTML 模板。

測試自定義 404 的方法

API 測試：使用 Postman 或 cURL

測試 JSON 響應

發送 GET 請求到一個不存在的 API 路徑，並設置 Accept: application/json 標頭。

• 使用 Postman：
  • 在 Headers 中添加 Accept: application/json。
  • 發送請求到 /api/nonexistent/。
• 使用 cURL：

curl -H "Accept: application/json" http://127.0.0.1:8000/api/nonexistent/  

• 預期結果：
  返回以下 JSON 響應：

{  
    "error": "Page not found",  
    "status_code": 404,  
    "detail": "The requested URL was not found on this server."  
}  

瀏覽器測試：檢查 HTML 響應

直接在瀏覽器中輸入一個不存在的 URL，例如 http://127.0.0.1:8000/nonexistent/，檢查是否正確加載 404.html 錯誤頁面。

最佳實踐與注意事項

確保 DEBUG=False

handler404 僅在 DEBUG=False 時啟用。

在開發環境中，DEBUG=True 時 Django 預設顯示調試頁面。

在 settings.py 中設置：

DEBUG = False  
ALLOWED_HOSTS = ['*']  

提供統一的錯誤頁模板

將 404.html 模板放在主應用（例如 core）的 templates 資料夾中，確保模板結構清晰且內容友好。

測試覆蓋多種請求情境

• 測試 API 請求與瀏覽器請求的返回內容是否符合預期。
• 確保所有未匹配路徑都能正確觸發自定義邏輯。

結語

通過配置 handler404，我們可以靈活地處理 404 錯誤頁，無論是前後端分離的 API 請求，還是普通的瀏覽器訪問，都能提供更好的用戶體驗。

這種設計適用於小型到大型項目，幫助開發者有效地管理未匹配路徑，提升應用的健壯性與用戶友好性。

現在就試著為你的項目添加自定義的 handler404 吧！如果遇到問題，歡迎隨時討論 😊