Django 报错 TemplateDoesNotExist at /payment/process/

2026-10-10支付阿杰

结论

把 process.html 放在应用的模板命名空间目录中，并在视图里使用完整的相对路径：

payment/
├── templates/
│   └── payment/
│       └── process.html
├── views.py
└── urls.py

return render(request, "payment/process.html", context)

还要确认 payment 已加入 INSTALLED_APPS，模板配置也已启用应用模板目录扫描。

推荐配置

settings.py：

INSTALLED_APPS = [
    # ...
    "payment",
]

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

payment/views.py：

from django.shortcuts import render


def process(request):
    context = {}
    return render(request, "payment/process.html", context)

payment/urls.py：

from django.urls import path

from . import views

urlpatterns = [
    path("process/", views.process, name="process"),
]

项目根路由：

from django.urls import include, path

urlpatterns = [
    path("payment/", include("payment.urls")),
]

为什么 Django 找不到模板

启用 APP_DIRS=True 后，Django 会到每个已安装应用的 templates 目录中查找模板。因此：

render(request, "payment/process.html")

对应的文件位置应为：

payment/templates/payment/process.html

中间的第二层 payment 是模板命名空间。虽然这层目录不是强制要求，但建议保留。否则，多个应用中如果都有名为 process.html 的模板，Django 可能会加载错误的文件。

常见问题是模板的实际路径与 render() 中传入的名称不一致。例如，文件位于：

payment/templates/payment/process.html

视图中却写成：

render(request, "process.html")

这样 Django 查找的是各个模板根目录下的 process.html，而不是 payment/process.html。

如果模板放在项目级目录

如果想把模板统一放在项目根目录的 templates 中，可以使用以下结构：

project_root/
├── manage.py
├── templates/
│   └── payment/
│       └── process.html
└── project_name/
    └── settings.py

然后在 settings.py 中显式添加该目录：

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                # 保留项目原有配置
            ],
        },
    },
]

视图中的模板路径不变：

return render(request, "payment/process.html")

排查要点

可以按以下顺序检查：

目录名应准确写成 templates，不能写成 template。
文件名必须与视图中的路径完全一致，包括大小写。
使用应用模板时，应用必须出现在 INSTALLED_APPS 中。
APP_DIRS 应设为 True。如果设为 False，需要自行配置模板加载器。
修改 settings.py 或移动模板后，重新启动开发服务器。
render() 接收的是模板名称，不是文件系统路径：

# 错误
render(request, "payment/templates/payment/process.html")

# 正确
render(request, "payment/process.html")

URL 配置只负责把请求交给对应的视图，不参与模板查找。如果错误已经出现在 /payment/process/ 对应的视图中，应检查 render() 中的模板名称、模板的实际位置和 TEMPLATES 配置。