第 4 章:Jinja2 模板与静态文件
Flask 最顺手的地方就是这一层:一个字典传进去,一套模板渲染出来。前提是别把业务逻辑写进模板里。
学习目标
- 会用继承组织页面,而不是每个文件复制一遍 header
- 会用宏与 include 复用片段
- 明白自动转义在挡什么,知道
|safe什么时候是危险的 - 会把静态文件与模板分开管,并处理缓存问题
4.1 模板放在哪
myapp/
├── app.py
├── templates/
│ ├── base.html
│ ├── index.html
│ └── partials/_nav.html
└── static/
├── css/app.css
└── img/logo.pngpython
@app.get("/")
def index():
return render_template("index.html", title="首页", items=ITEMS)render_template 按模板名查找,默认在应用根目录下的 templates/。用工厂模式时,路径取决于 Flask(__name__) 拿到的包名(第 5 章会踩这个坑)。
4.2 三种语法
jinja
{{ user.name }} {# 输出表达式,自动转义 #}
{% if user.is_admin %}…{% endif %} {# 语句 #}
{% for item in items %}…{% endfor %}
{# 这是注释,不会出现在页面里 #}几个模板里的"内置函数":
| 写法 | 作用 |
|---|---|
loop.index / loop.first / loop.last | 循环元信息 |
x or "默认值" | 空值兜底 |
price | round(2) | 过滤器 |
data | tojson | 安全地塞进 JS |
4.3 继承:只写差异
jinja
{# templates/base.html #}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>{% block title %}陌阡{% endblock %}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='css/app.css') }}">
</head>
<body>
{% include "partials/_nav.html" %}
<main>{% block content %}{% endblock %}</main>
</body>
</html>jinja
{# templates/index.html #}
{% extends "base.html" %}
{% block title %}首页 · 陌阡{% endblock %}
{% block content %}
<h1>最新文章</h1>
{% for post in posts %}
<article>{{ post.title }}</article>
{% endfor %}
{% endblock %}4.4 宏与 include
jinja
{# templates/macros.html #}
{% macro badge(text, kind="info") %}
<span class="badge badge-{{ kind }}">{{ text }}</span>
{% endmacro %}jinja
{% from "macros.html" import badge %}
{{ badge("已完成", "success") }}| 手段 | 适合 | 不适合 |
|---|---|---|
extends | 整页骨架 | 局部片段 |
include | 固定片段(导航、页脚) | 需要传参的片段 |
macro | 带参数的重复 HTML | 整页布局 |
4.5 过滤器
内置的够用一半,常用的记住这几个:
| 过滤器 | 例子 | 结果 |
|---|---|---|
default | {{ name | default("游客") }} | 空值时兜底 |
length | {{ items | length }} | 数量 |
join | {{ tags | join("、") }} | 拼字符串 |
round | {{ 3.1415 | round(2) }} | 3.14 |
tojson | {{ data | tojson }} | 转义好的 JSON |
safe | {{ html | safe }} | 关掉转义,慎用 |
自定义:
python
@app.template_filter("money")
def money(cents: int) -> str:
return f"¥{cents / 100:.2f}"jinja
{{ order.total_cents | money }}4.6 自动转义在挡什么
Jinja2 对 .html 模板默认开启自动转义,把 <script> 变成 <script>。
这是 XSS 的第一道防线,但两种情况下会失效:
- 用了
|safe:等于告诉模板"这段我担保"; - 在 JS 里手拼:
<script>var name = "{{ user.name }}";</script>,转义对 JS 字符串上下文不完全适用。
正确写法是用 tojson:
jinja
<script>var name = {{ user.name | tojson }};</script>一句原则:用户可控的内容,永远不要 |safe。富文本要展示,就在后端用白名单清洗(如 bleach),再标记为安全。
4.7 静态文件
jinja
<link rel="stylesheet" href="{{ url_for('static', filename='css/app.css') }}">
<img src="{{ url_for('static', filename='img/logo.png') }}" alt="logo">三个要点:
- 路径不要手写
/static/...,用url_for; - 生产环境让 Nginx 直接发静态文件,Flask 不参与;
- 缓存:给文件名加内容哈希(
app.a1b2c3.css),或配置SEND_FILE_MAX_AGE_DEFAULT。
python
app.config["SEND_FILE_MAX_AGE_DEFAULT"] = 3600 # 秒;开发时设 0 便于调试4.8 上下文处理器
每个页面都要用的变量(站点名、当前用户、导航),别在每个视图里传:
python
@app.context_processor
def inject_globals():
return {"site_name": "陌阡", "year": 2026}模板里直接 {{ site_name }}。注意:它每次渲染都会执行,别在里面查数据库。
4.9 模板里的三条红线
| 红线 | 为什么 |
|---|---|
| 不写业务计算 | 模板里做金额计算、权限判断,测试没法覆盖 |
| 不查数据库 | 模板里调 Model.query 会把查询散落在各处 |
| 不吞异常 | {{ x.y.z }} 缺字段时静默为空,问题被藏起来 |
模板只做一件事:把已经准备好的数据摆到正确的位置。
本章小结
| 要点 | 说明 |
|---|---|
| 位置 | 默认 templates/,静态文件在 static/ |
| 继承 | extends + block,只写差异 |
| 复用 | include 片段、macro 带参片段 |
| 过滤器 | default / length / join / tojson / safe |
| 安全 | 自动转义默认开,` |
| 静态文件 | url_for('static'),生产交给 Nginx,注意缓存 |
| 全局变量 | context_processor,别做重活 |
下一章
应用工厂:为什么单文件写到最后会崩,create_app 怎么解决,配置怎么分层。