starlette 集成 jinja2 模板引擎的核心做法是实例化 jinja2.environment 并配合 starlette.templating.jinja2templates 类。你需要指定模板文件的加载路径,然后在路由处理函数中调用 templates.templateresponse 方法渲染 html 页面。这样即可在 starlette 应用中无缝使用 jinja2 的变量替换和逻辑控制功能。

如何配置模板加载器与基础环境
配置过程主要依赖 FileSystemLoader 来定位模板文件,并将其传递给 Jinja2Templates 构造函数。这一步确保了应用能正确读取磁盘上的 HTML 文件,并为后续的渲染提供基础上下文。

import os
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import HTMLResponse
from starlette.templating import Jinja2Templates
# 定义模板目录
TEMPLATE_DIR = "templates"
# 初始化 Jinja2 模板环境
templates = Jinja2Templates(directory=TEMPLATE_DIR)
async def home(request):
# 渲染模板并返回响应
return templates.TemplateResponse(
"index.html",
{"request": request, "title": "Home Page"}
)
app = Starlette(routes=[Route("/", home)])
上述代码展示了最基础的集成方式。通过设置 directory 参数,Jinja2Templates 内部会自动创建一个 Jinja2 环境。在 home 函数中,我们传入请求对象和自定义数据字典。注意,request 对象必须显式传递,因为 Jinja2 默认不包含它,而 Starlette 的某些内置变量(如 URL 生成)依赖于它。
如何处理动态数据与模板继承
在实际开发中,通常需要展示动态内容或复用布局。Jinja2 支持通过字典传递任意数据,并利用 {% extends %} 标签实现模板继承。这使得你可以将导航栏、页脚等公共部分提取到基模板中,子模板只需填充特定区块。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

<!-- templates/base.html -->
<title>{{ title }}</title><nav>Navigation Bar</nav>
{% block content %}{% endblock %}
<!-- templates/index.html -->
{% extends "base.html" %}
{% block content %}
<h1>Hello {{ name }}</h1>
<p>Current time: {{ now }}</p>
{% endblock %}
在路由函数中,你只需准备包含 name 和 now 的数据字典。Jinja2 引擎会在渲染时自动解析这些变量。如果数据中包含列表或复杂对象,Jinja2 也能通过点号语法访问其属性。这种机制让前端展示层与后端逻辑保持清晰分离。
当模板文件中缺少指定变量时会发生什么
如果在模板中引用了未在上下文中提供的变量,Jinja2 默认会抛出 UndefinedError 异常。这会导致 HTTP 500 错误。为了避免这种情况,可以在初始化 Jinja2Templates 时配置 undefined 参数,或者在模板中使用 {% if variable is defined %} 进行判断。此外,Starlette 的异常处理器可以捕获此类错误并返回友好的错误页面。










