Django中已存在的引用模板触发TemplateDoesNotExist错误

我在realestate/settings.py里的模板配置是这样的：

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

然后我有一个模板片段，需要引用另一个不同文件夹里的模板片段：

路径是templates\partials\listings\detail\user_card.html，代码如下：

{% load static %}
{# Card #}
<div class="card mb-3">
  <div class="row row-cols-sm-2 row-cols-md-1 g-0">
    {# Card image #}
    <div class="col">
      <img class="rounded-circle w-50 mx-auto my-3" src="{% static '/images/avatar-3814081_640.png' %}" alt="Avatar">
    </div>

    {# Card body #}
    <div class="col">
      <div class="card-body">
        <a class="text-decoration-none" href="{% url 'user-detail' user.id %}">
          <h2 class="card-title fw-bold">{{ user }}</h2>
        </a>
      </div>
    </div>
  </div>

  {% include "../../users/detail/footer" %} {# template already exists #}
</div>

现在我遇到了TemplateDoesNotExist错误，提示找不到partials/users/detail/footer，但这个模板明明是存在的。我试过用{% include "partials/users/detail/footer" %}也不行。

我的文件夹结构如下：

解决方案 #

咱们一步步来排查问题，Django模板引用的逻辑其实很清晰，可能只是细节没注意到：

1. 先补上模板文件的.html后缀
   你大概率是漏了模板文件的后缀名！Django默认需要指定完整的文件名（包括.html），除非你自己改了加载器的配置。试试把include语句改成下面这样：

   {% include "partials/users/detail/footer.html" %}
   

   要是想用相对路径（从当前user_card.html的位置往上找），就写成：

   {% include "../../users/detail/footer.html" %}
   

   这应该是最常见的原因，我自己也经常犯这个错😂

2. 核对文件路径和拼写
   仔细检查你的footer.html是不是真的在templates/partials/users/detail/下面，文件名有没有写错（比如把footer写成foot，或者大小写问题——Windows系统不区分大小写，但要是以后部署到Linux服务器就会踩坑）。

3. 排除其他app的模板干扰
   你设置了APP_DIRS: True，这意味着Django会去每个已安装app的templates目录下找模板。如果你的项目里有其他app的templates目录下也有partials/users/detail/footer.html，可能会导致查找优先级的问题。可以临时把APP_DIRS改成False，测试下能不能找到你的模板，排除这个干扰。

4. 用调试页面看Django实际找了哪些路径
   打开Django的调试模式（DEBUG: True），当出现TemplateDoesNotExist错误时，页面底部会列出Django所有尝试查找的模板路径。你可以对照这些路径，看看是不是你要找的文件路径不在里面，这样就能精准定位问题了。

备注：内容来源于stack exchange，提问作者IgorArnaut