在 Jinja2 中添加自定义函数需在 Python 层注册到 env.globals，过滤器则注册到 env.filters；二者不可同名，否则过滤器优先导致全局函数失效；注册须在加载模板前完成，且函数参数需显式声明，避免 *args/**kwargs。
怎么在 Jinja2 模板里加自定义函数
直接往 Jinja2 环境里注册函数，不是改模板语法，也不是写插件——模板本身不“支持”函数扩展，是 Python 层把函数塞进去的。
常见错误：在模板里写 {% def my_func() %} 或试图用 globals 以外的方式注入，结果报 UndefinedError 或静默失效。
- 必须在创建
Environment实例后、加载模板前，调用env.globals.update(...)或env.globals['func_name'] = func - 函数参数要明确，Jinja2 不支持 *args/**kwargs 透传；比如
def format_date(dt, fmt='%Y-%m-%d')可以，但def wrapper(*a, **kw)会崩 - 避免在函数里做耗时操作（如查数据库），模板渲染是同步阻塞的，一次慢就拖垮整个响应
示例：
from jinja2 import Environment env = Environment() env.globals['truncate'] = lambda s, n: s[:n] + '...' if len(s) > n else s之后模板中就能用
{{ truncate('hello world', 5) }}。
怎么写自定义过滤器（filter）
过滤器比全局函数更常用，也更安全——它天然只接收一个值（管道左边的输出），语义清晰，调试也容易。
典型翻车现场：写成 def upper_first(value, delim=' ') 后，在模板里写 {{ name | upper_first('_') }}，结果报 TypeError: upper_first() takes 1 positional argument but 2 were given。
- Jinja2 过滤器默认只传第一个参数（即管道前的值），额外参数必须显式声明为关键字参数，且调用时用括号：
{{ name | upper_first(delim='_') }} - 注册方式是
env.filters['upper_first'] = upper_first，不是globals - 过滤器返回值类型最好和输入一致（str → str，list → list），否则容易引发后续模板里
for循环或if判断出错
示例：
def snake_to_camel(s):
return ''.join(x.capitalize() for x in s.split('_'))
env.filters['snake_to_camel'] = snake_to_camel模板中：{{ 'user_name' | snake_to_camel }} → UserName。
为什么 filter 和 global 函数不能混着用同名标识符
因为 Jinja2 查找顺序是：过滤器 → 测试器 → 全局变量。一旦你注册了 env.filters['json']，再注册 env.globals['json'] 就没用了——模板里 {{ data | json }} 走过滤器，{{ json(data) }} 却会报错说 json is not callable（因为被过滤器占位了）。
- 名字冲突不是警告，是静默覆盖，调试时很难发现
- 如果真需要同名多用途，建议加前缀区分，比如
to_json（函数）、json_pretty（过滤器） - Django 模板里叫
filter，Jinja2 里叫filter，但 Flask 默认没开autoescape时，自定义过滤器若返回未转义 HTML，可能引发 XSS——这点常被忽略
模板函数扩展后怎么测试是否生效
别等上线才发现函数没注册上。最简单的验证方式：在模板里直接调用并用 is defined 判断。
- 写个临时测试模板：
{{ my_util_func is defined }} {{ my_util_filter is defined }}，输出全是True才算到位 - 如果用 Flask，记得检查是否在
app.jinja_env上注册，而不是另建了一个Environment实例（后者完全不影响 Flask 渲染） - 单元测试里别 mock 模板字符串，而是构造真实
Template实例并render()，捕获TemplateSyntaxError或UndefinedError
复杂点在于环境隔离：CLI 工具、Web 请求、异步任务可能用不同 Environment 实例，函数得挨个注册，漏一个就报错。
