Django自定义404页面无法生效，两种配置方案均失败

基础配置确认 #

• 确保ALLOWED_HOSTS已正确配置（DEBUG=False时必须设置，否则会返回500错误而非404），示例：ALLOWED_HOSTS = ['your-domain.com', 'localhost']
• 检查INSTALLED_APPS中是否包含django.contrib.staticfiles，静态资源加载失败可能导致页面显示异常

方案一（根模板404.html）排查 #

• 确认模板文件名是小写的404.html，Django对模板文件名大小写敏感，Linux环境下尤其要注意，避免写成404.HTML
• 验证模板目录路径正确性：在项目根目录执行python manage.py shell，输入以下命令查看实际配置的模板路径：

  from django.conf import settings; print(settings.TEMPLATES[0]['DIRS'])
  

  确认输出包含你的templates目录绝对路径
• 检查404.html内容是否有模板语法错误，比如标签闭合不全、变量引用错误，这类问题会导致渲染失败回退到默认页面
• 测试时必须访问完全不存在的路由，比如/non-existent-path/，不要用已配置的路由测试

方案二（自定义handler404视图）排查 #

• handler404必须在项目根urls.py中设置，而非app的urls.py，Django仅读取根配置文件中的handler配置
• 确保视图函数符合Django版本要求：3.2+的自定义404视图必须接收exception参数，示例代码：

  from django.shortcuts import render
  
  def not_found(request, exception):
      return render(request, 'partials/not_found.html', status=404)
  

• 确认模板路径正确：检查templates目录下是否存在partials子目录，且该目录下有not_found.html文件
• 执行python manage.py check排查是否有导入错误、视图配置错误等问题

额外验证步骤 #

• 清理Django缓存：执行python manage.py clearcache，避免旧模板缓存导致的显示异常
• 查看服务器日志（如Nginx/Apache日志或Django的django.log），定位是否存在模板未找到、静态资源加载失败等具体错误

内容的提问来源于stack exchange，提问作者user22236133