Django自定义包可配置模板文件夹选择功能实现方案咨询

核心问题解答 #

• 关于django-crispy-forms的实现：你没有理解遗漏，它的模板包逻辑是组件渲染时动态拼接模板路径，不适用于你全局继承基础模板的场景，硬改所有{% extends %}路径确实成本过高。
• 模板加载器是完全适配你需求的解决方案：通俗来说，Django的模板加载器就是负责按照配置规则，在指定路径列表里逐个查找你请求的模板文件的工具，你需要的「根据配置变量优先查找指定子目录下的模板」的需求，完全可以通过调整模板查找规则实现。

推荐实现方案（零修改现有模板，成本最低） #

这个方案不用自定义加载器，仅通过动态注入模板查找路径即可实现，完全满足你的三个目标：

步骤1：调整自定义包的目录结构 #

仅新增新版模板的子文件夹，原有旧模板保持原位不动：

MYCUSTOMPACKAGE/src/
├─ custom_package/ # 你的包代码目录
│  ├─ __init__.py
│  └─ ... # 其他工具类、视图代码
└─ templates/ # 原有模板根目录
   ├─ xyz/ # 原有旧模板文件夹，完全不动
   │  └─ base.html # 原有旧模板，不用修改
   └─ v2/ # 新增的新版模板子文件夹
      └─ xyz/
         └─ base.html # 新版模板，路径和旧模板保持一致，仅外层多了v2目录

步骤2：在自定义包中添加动态路径注入逻辑 #

在自定义包的__init__.py中添加如下代码，自动把配置的子文件夹路径加到Django模板查找优先级最高的位置：

import os
from django.conf import settings

# 自动获取当前包的模板根目录绝对路径，不管包安装在什么位置都能正确识别
PACKAGE_TEMPLATE_ROOT = os.path.join(
    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
    "templates"
)
# 读取项目settings中配置的模板子文件夹，默认空值代表使用旧版模板
CUSTOM_PACK_TEMPLATE_DIR = getattr(settings, "CUSTOM_PACK_TEMPLATE_DIR", "")

if CUSTOM_PACK_TEMPLATE_DIR:
    target_dir = os.path.join(PACKAGE_TEMPLATE_ROOT, CUSTOM_PACK_TEMPLATE_DIR)
    if os.path.isdir(target_dir):
        # 将指定子文件夹插到模板查找路径的最前面，优先级最高
        settings.TEMPLATES[0]["DIRS"].insert(0, target_dir)

步骤3：主项目按需配置即可 #

需要使用新版模板的项目，只需要在自己的settings.py中添加一行配置即可：

CUSTOM_PACK_TEMPLATE_DIR = "v2"

不需要更新的旧项目不用做任何修改，默认继续使用原有旧模板，后续你推送自定义包的安全更新时，旧项目升级包版本也不会受到任何影响。

补充：自定义模板加载器的实现（如果需要更复杂的规则） #

如果后续你需要更灵活的模板查找逻辑（比如按不同应用匹配不同版本模板），可以用自定义加载器实现，逻辑和上面的路径注入本质一致：

1. 在自定义包中新增template_loaders.py：

from django.template.loaders.filesystem import Loader as FileSystemLoader
from django.conf import settings
import os

class VersionedTemplateLoader(FileSystemLoader):
    def get_template_sources(self, template_name, template_dirs=None):
        # 读取配置的子文件夹
        sub_dir = getattr(settings, "CUSTOM_PACK_TEMPLATE_DIR", "")
        if sub_dir:
            # 先拼接子目录路径查找
            versioned_name = os.path.join(sub_dir, template_name)
            for result in super().get_template_sources(versioned_name, template_dirs):
                yield result
        # 没找到就回落原路径查找
        for result in super().get_template_sources(template_name, template_dirs):
            yield result

2. 主项目在settings.py的TEMPLATES配置中添加加载器即可：

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        # 把自定义加载器放到最前面
        "LOADERS": [
            "custom_package.template_loaders.VersionedTemplateLoader",
            "django.template.loaders.filesystem.Loader",
            "django.template.loaders.app_directories.Loader",
        ],
        ...
    }
]

关于包路径识别的问题 #

你提到的包不在site-packages也不在项目目录下的问题，只要你的包已经被正确添加到Python的sys.path中（比如通过pip install -e开发模式安装，或者手动在settings中添加包路径到sys.path），上面的自动获取绝对路径的逻辑都可以正常识别，不需要手动写死路径。

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