Skip to content
Lv3Flask 速成进度 4 / 8

第 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.png
python
@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 %}
一个 base 撑起所有页面,子模板只填洞base.htmlhead / nav …{% block content %}{% endblock %}footer …index.htmlextends base,填 contentpost.htmlextends base,填 content + titlepartials/_nav.htmlinclude:不参与继承,纯片段三条规矩extends 只能出现一次,且在最前block 可嵌套,子模板可调 super()include 是复制片段,宏才是"函数"判断标准:页面结构重复 → 继承;局部片段重复 → include;一个带参数的片段 → 宏。

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> 变成 &lt;script&gt;。

这是 XSS 的第一道防线,但两种情况下会失效:

  1. 用了 |safe:等于告诉模板"这段我担保";
  2. 在 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 怎么解决,配置怎么分层。

本文阅读--次|全站访问--次|访客--人