介绍

Jinja2 是 Python 生态中最主流的模板引擎，由 Armin Ronacher（Flask 作者）开发，广泛用于 Flask、FastAPI、Sphinx、Ansible、SaltStack 等项目，用来把模板文本 + 数据渲染成最终文本（HTML、配置文件、shell脚本等）。

官方文档：http://jinja.pocoo.org/
中文文档：http://docs.jinkan.org/docs/jinja2/

为什么要使用模板

比如上面的淘宝网页，样式是固定的，但内容是动态变化的，不论搜索什么商品，都是这个界面，像这种情况就适合使用模板

实现原理

模板 = 静态文本 + 占位/逻辑标记，填入变量输出最终内容。

类比

类似Python的 f 字符串，通过标记 {变量/表达式} ，将变量的值直接嵌入文本：

name = "张三"
age = 22
s = f"姓名：{name}，年龄：{age}"
print(s)

输出：姓名：张三，年龄：22

特点

语法简洁，类 Python，变量渲染：{{ var }}
高性能：模板会编译成 Python 字节码缓存，多次渲染不需要重复解析，性能优秀。
完整错误提示：模板报错会显示模板文件名、行号，方便调试定位。
模板继承、包含、宏：实现页面复用，解决重复代码。
支持过滤器、测试器、自定义扩展，可接入Python函数。
沙箱模式：可以限制模板可执行操作，适合外部用户上传模板的场景。
自动转义：默认开启 HTML 转义，防止 XSS；渲染配置文件时可关闭。

安装

pip 安装

pip install jinja2

uv 安装

uv add jinja2

基础语法

1. 三种定界符

{{ 变量表达式 }}      {# 输出值 #}
{% 控制语句 %}        {# if、for、block、macro 逻辑 #}
{# 注释，不会输出 #}

2. 变量与过滤器 `|`

{# 变量输出 #}
{{ name }}
{{ user.age }}
{{ user['age'] }}

{# 过滤器：管道符 |，链式调用 #}
{{ name | upper }}          {# 转大写 #}
{{ num | default(0) }}      {# 默认值 #}
{{ content | escape }}      {# html转义，默认开启 #}
{{ list | join(',') }}

常用内置过滤器：upper、lower、length、reverse、safe（关闭转义）、int、round、default。

3. 条件判断

{% if score >= 60 %}
及格
{% elif score >= 80 %}
良好
{% else %}
不及格
{% endif %}

4. for循环

<ul>
{% for item in items %}
    <li>{{ loop.index }} - {{ item }}</li>
{% endfor %}
</ul>

循环内置变量 loop：

loop.index：从1开始序号
loop.index0：从0开始
loop.first / loop.last：是否第一条/最后一条
loop.length：列表长度

5. 模板继承（最常用）

父模板 base.html

<!DOCTYPE html>
<html>
<body>
{% block content %}{% endblock %}
</body>
</html>

子模板

{% extends "base.html" %}

{% block content %}
<h1>页面内容</h1>
{% endblock %}

6. 宏 macro（类似函数）

{% macro input(name, value='') %}
<input name="{{name}}" value="{{value}}">
{% endmacro %}

{{ input('username') }}

7. include 引入片段

{% include "header.html" %}

Python 代码调用 Jinja2

方式1：字符串模板

from jinja2 import Template

tpl = Template("Hello {{ name }}!")
result = tpl.render(name="Jinja2")
print(result) # Hello Jinja2!

方式2：从文件加载模板（项目常用）

from jinja2 import Environment, FileSystemLoader

# 指定模板文件夹
env = Environment(loader=FileSystemLoader("./templates"))
tpl = env.get_template("demo.html")
out = tpl.render(title="标题", users=[1,2,3])
print(out)

使用场景

Web后端渲染HTML：Flask 默认模板引擎；FastAPI 可整合 Jinja2Templates。
生成配置文件：Ansible 大量使用 Jinja2 渲染 nginx、systemd 配置。
代码生成：自动生成 Python、C、SQL、Shell脚本。
文档生成：Sphinx文档工具。

原文出处：/show_1GW3riTvjdyN.html

介绍