求助：通过pip安装的Django App模板加载器无法加载模板

我之前也碰到过一模一样的情况——本地开发时模板加载毫无问题，打包上传PyPI再用pip安装后，就开始报TemplateDoesNotExist，而且看调试信息发现Django根本没去检索我的App模板目录。核心问题大概率出在打包环节没把模板文件正确包含到发布包里，或者Django无法识别你的App模板路径，下面一步步来排查解决：

1. 先检查打包配置是否包含模板文件 #

用pip安装包时，只有打包时被明确标记的文件才会被安装到虚拟环境中。如果你的模板文件没被包含，Django自然找不到它们。

如果你用setup.py打包 #

确保setup.py里有package_data配置，或者开启include_package_data=True：

from setuptools import setup, find_packages

setup(
    name="your-app-name",
    version="0.1.0",
    packages=find_packages(),
    # 方式1：明确指定要包含的模板文件
    package_data={
        "your_app_name": ["templates/**/*.html", "templates/**/*.txt"]
    },
    # 方式2：配合MANIFEST.in自动包含非代码文件（推荐）
    include_package_data=True,
)

如果用方式2，需要在项目根目录创建MANIFEST.in文件，内容如下：

recursive-include your_app_name/templates *

如果你用pyproject.toml（现代打包方式） #

在pyproject.toml里添加模板文件的包含规则：

[tool.setuptools.package-data]
"your_app_name" = ["templates/**/*.html"]

或者开启自动包含非代码文件：

[tool.setuptools]
include-package-data = true

同样需要配合上面的MANIFEST.in文件来指定模板目录。

2. 验证安装后的包是否包含模板 #

安装你的App后，去虚拟环境的site-packages目录找到你的App文件夹，确认templates目录和里面的文件是否存在。比如：

# 虚拟环境路径示例，替换成你的实际路径
venv/lib/python3.11/site-packages/your_app_name/templates/

如果这个目录不存在，说明打包时没把模板包含进去，回到第一步修正配置。

3. 确认App的配置名称完全一致 #

确保你的App的apps.py里的name参数，和INSTALLED_APPS里添加的名称完全匹配：
比如your_app_name/apps.py：

from django.apps import AppConfig

class YourAppNameConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "your_app_name"  # 这个要和INSTALLED_APPS里的名字一模一样

settings.py里的INSTALLED_APPS应该是：

INSTALLED_APPS = [
    ...,
    "your_app_name",
    ...,
]

4. 清除缓存并重启服务（可选） #

有时候Django的缓存会导致它没识别到新安装的App的模板，你可以尝试：

• 执行python manage.py clearcache清除模板缓存
• 彻底重启你的开发服务器
• 如果之前修改过TEMPLATES里的加载器，暂时改回调试模式默认的django.template.loaders.app_directories.Loader

5. 手动指定模板路径（兜底方案） #

如果上面的方法都没用，可以在项目的settings.py的TEMPLATES配置里手动添加你的App模板路径：

import os
from pathlib import Path

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

TEMPLATES = [
    {
        ...,
        "DIRS": [
            BASE_DIR / "templates",
            # 替换成你的虚拟环境中App模板的实际路径
            os.path.join(BASE_DIR, "venv/lib/python3.11/site-packages/your_app_name/templates"),
        ],
        ...,
    },
]

不过这个方法不推荐，因为不同环境的虚拟环境路径可能不同，最好还是通过正确打包来解决根本问题。

最后提醒：每次修改打包配置后，要重新构建包并上传到test.pypi，再重新安装你的App，不然旧的包还是没有模板文件。

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