Django中TemplateDoesNotExist错误：自定义错误模板无法找到

问题现象 #

触发500错误时，持续抛出TemplateDoesNotExist: 500.html异常，正常页面模板加载无问题，仅错误处理流程中出错。

报错堆栈 #

Traceback (most recent call last):
  File "/usr/local/Cellar/python@3.9/3.9.10/Frameworks/Python.framework/Versions/3.9/lib/python3.9/wsgiref/handlers.py", line 137, in run
    self.result = application(self.environ, self.start_response)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/core/handlers/wsgi.py", line 132, in __call__
    response = self.get_response(request)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/core/handlers/base.py", line 140, in get_response
    response = self._middleware_chain(request)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/core/handlers/exception.py", line 57, in inner
    response = response_for_exception(request, exc)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/core/handlers/exception.py", line 139, in response_for_exception
    response = handle_uncaught_exception(
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/core/handlers/exception.py", line 184, in handle_uncaught_exception
    return callback(request)
  File "/Users/Tom/Desktop/squeasy /tasks/views.py", line 31, in handler500
    response = render(request, template_name)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/shortcuts.py", line 24, in render
    content = loader.render_to_string(template_name, context, request, using=using)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/template/loader.py", line 61, in render_to_string
    template = get_template(template_name, using=using)
  File "/Users/Tom/.local/share/virtualenvs/squeasy_-djXBooHN/lib/python3.9/site-packages/django/template/loader.py", line 19, in get_template
    raise TemplateDoesNotExist(template_name, chain=chain)
django.template.exceptions.TemplateDoesNotExist: 500.html

当前配置信息 #

settings.py 中 TEMPLATES 配置 #

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR /'squeasy/tasks/templates/tasks'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

尝试过的 TEMPLATES 配置变体 #

• 配置1：

  'DIRS': [],
  'APP_DIRS': True,
  

• 配置2：

  'DIRS': [os.path.join(BASE_DIR, 'templates')],
  

• 配置3：

  'DIRS': [BASE_DIR/'templates'],
  

错误处理视图（tasks/views.py） #

def handler400(request, exception, template_name = "400.html"):
    response = render(request, template_name)
    response.status_code = 400
    return response

def handler403(request, exception, template_name = "403.html"):
    response = render(request, template_name)
    response.status_code = 403
    return response

def handler404(request, exception, template_name="404.html"):
    response = render(request, template_name)
    response.status_code = 404
    return response

def handler500(request, template_name="500.html"):
    response = render(request, template_name)
    response.status_code = 500
    return response

项目根 urls.py 配置 #

handler400 = 'tasks.views.handler400'
handler403 = 'tasks.views.handler403'
handler404 = 'tasks.views.handler404'
handler500 = 'tasks.views.handler500'

其他关键配置 #

• DEBUG = False
• 错误处理视图所属应用为 tasks

解决方法 #

1. 确认模板文件路径正确性 #

根据你的配置选择对应模板存放位置：

• 应用内模板：确保 tasks 应用下存在 templates/tasks/500.html、400.html 等文件，路径为 tasks/templates/tasks/500.html
• 项目级模板：在项目根目录创建 templates 文件夹，将错误模板直接放在该目录下（即 templates/500.html），同时确保 TEMPLATES 的 DIRS 配置正确指向该目录：

  'DIRS': [BASE_DIR / 'templates'],
  

2. 修复500错误视图的上下文问题 #

当 DEBUG=False 时，Django处理500错误的上下文环境受限，需显式传入空上下文避免加载异常：

def handler500(request, template_name="500.html"):
    response = render(request, template_name, {})
    response.status_code = 500
    return response

同时检查模板文件，避免使用仅在DEBUG模式下可用的变量（如debug上下文变量）。

3. 验证模板查找路径 #

通过Django shell查看模板搜索路径，确认你的模板是否在范围内：

python manage.py shell
from django.template.loader import get_template_sources
print(list(get_template_sources('500.html')))

若输出路径中无目标模板位置，需调整模板存放路径或TEMPLATES配置。

4. 确认应用已注册 #

确保 tasks 应用添加到 INSTALLED_APPS：

INSTALLED_APPS = [
    # ... 其他应用
    'tasks',
]

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