Jinja2：Python最主流的模板引擎-马育民老师

# 介绍

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

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

# 为什么要使用模板

[![](https://www.malaoshi.top/upload/0/0/1EF3VDm0zxwf.png)](https://www.malaoshi.top/upload/0/0/1EF3VDm0zxwf.png)

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

# 实现原理

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

### 类比

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

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

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

# 特点

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

# 安装

### pip 安装

```bash
pip install jinja2
```

### uv 安装

```
uv add jinja2
```

# 基础语法

### 1. 三种定界符
```jinja2
{{ 变量表达式 }}      {# 输出值 #}
{% 控制语句 %}        {# if、for、block、macro 逻辑 #}
{# 注释，不会输出 #}
```

### 2. 变量与过滤器 `|`
```jinja2
{# 变量输出 #}
{{ name }}
{{ user.age }}
{{ user['age'] }}

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

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

### 3. 条件判断
```jinja2
{% if score >= 60 %}
及格
{% elif score >= 80 %}
良好
{% else %}
不及格
{% endif %}
```

### 4. for循环
```jinja2
<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
```jinja2
<!DOCTYPE html>
<html>
<body>
{% block content %}{% endblock %}
</body>
</html>
```
子模板
```jinja2
{% extends "base.html" %}

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

### 6. 宏 macro（类似函数）
```jinja2
{% macro input(name, value='') %}
<input name="{{name}}" value="{{value}}">
{% endmacro %}

{{ input('username') }}
```

### 7. include 引入片段
```jinja2
{% include "header.html" %}
```

# Python 代码调用 Jinja2

### 方式1：字符串模板
```python
from jinja2 import Template

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

### 方式2：从文件加载模板（项目常用）
```python
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)
```

# 使用场景

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

原文出处：/show_1GW3riTvjdyN.html