Django自定义模板标签必须满足三条件：置于templatetags/目录、模块中声明register=template.Library()、文件名合法（如mytags.py）；缺一则{% load %}静默失败，本质是未加载模块而非语法错误。
怎么在 Django 里写一个能用的自定义模板标签
直接能用的自定义模板标签，必须满足三个硬性条件：放在 templatetags/ 子目录下、模块里调用 register = template.Library()、文件名不含特殊字符（比如不能叫 my-tags.py）。漏掉任意一条，{% load xxx %} 就会静默失败——不是报错，而是根本找不到标签。
常见错误现象：Invalid block tag on line X: 'my_tag', expected 'endblock' 或者页面上原样输出 {% my_tag %}。本质是 Django 没加载到这个模块，而不是语法写错了。
- 应用目录下必须有
templatetags/文件夹，且该文件夹内含__init__.py（可以为空） - 自定义标签文件（如
mytags.py）要放在templatetags/下，不能嵌套子目录 - 模板开头必须显式
{% load mytags %}，名字必须和文件名一致（不含.py） - Django 2.0+ 要求模板标签模块不能被 INSTALLED_APPS 之外的应用导入，否则
templatetags不会被扫描
simple_tag 和 inclusion_tag 的核心区别在哪
simple_tag 返回字符串，适合做计算、拼接、格式化；inclusion_tag 返回渲染后的 HTML 片段，适合复用带结构的组件（比如分页栏、卡片头）。选错类型会导致逻辑混乱或 XSS 风险。
使用场景差异明显：simple_tag 常用于生成 URL、时间戳、状态 badge 文本；inclusion_tag 更适合封装需要独立上下文和 HTML 结构的模块。
立即学习“Python免费学习笔记（深入）”；
强戈环形山: q15040409-刻画家功能概述强戈环形山: q15040409-刻画家是一项面向实际任务的技能，主要用于平顶山: 维西翁: 1:1.0. 塔格斯: rap.github: 自动化。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该
-
simple_tag默认自动转义返回值，若需输出原始 HTML，得加is_safe=True参数，但必须确保内容可信 -
inclusion_tag的模板路径是相对于应用的templates/目录，不是相对于templatetags/ -
inclusion_tag接收的参数会传入新模板上下文，原模板变量不可见，除非显式用takes_context=True - 性能上，
simple_tag开销更小；inclusion_tag多一次模板解析，但利于结构解耦
为什么自定义过滤器比标签更适合处理单值转换
过滤器本质是函数式变换，输入一个值、输出一个值，语义清晰。用标签硬套单值处理（比如 {% format_phone number %}）反而破坏模板可读性，也容易和上下文变量名冲突。
常见错误是把 phone_number|format_phone 写成 {% format_phone phone_number %}，后者无法链式使用、不能配合 default 等内置过滤器，还让模板逻辑变重。
- 过滤器注册用
@register.filter，函数必须只接受 1–2 个参数（第二个是可选参数） - 过滤器不支持关键字参数，调用时只能用冒号传参：
{{ value|add:"2" }}，不能写{{ value|add:amount=2 }} - 如果过滤器可能返回 None 或空值，记得在函数里处理，否则模板渲染时报
TypeError: expected string or bytes-like object - Django 默认对过滤器结果转义，若返回 HTML 字符串，要用
@register.filter(is_safe=True)并确保内容安全
本地开发时 {% load %} 总是不生效怎么办
最常被忽略的是 Python 模块导入路径问题：Django 只扫描 INSTALLED_APPS 列表里的应用下的 templatetags/，哪怕你把标签文件放在项目根目录或某个工具包里，也不会被加载。
另一个隐蔽坑是缓存：Django 在 DEBUG=False 时会缓存模板编译结果，改了 templatetags 文件却没效果，八成是没重启服务器，或者没清模板缓存。
- 确认该应用已加入
INSTALLED_APPS，且名字和实际 Python 包名一致（比如'myapp'，不是'apps.myapp'） - 检查
templatetags/mytags.py里有没有语法错误，哪怕一个缩进错，整个模块都会加载失败，且无提示 - DEBUG=True 时修改模板标签文件会热重载，但修改后首次加载模板仍可能用旧缓存，强制刷新浏览器或清
__pycache__ - 用
python manage.py shell手动测试：from myapp.templatetags.mytags import register; print(register.tags)，看是否注册成功
复杂点在于跨应用复用：如果多个应用都要用同一套标签，别复制粘贴，应该抽成独立的 Python 包，然后确保它在 INSTALLED_APPS 里，并且 templatetags/ 路径能被 Django 扫描到。路径和导入关系一旦错一层，就全白忙。
