starlette 通过挂载 staticfiles 中间件来处理静态文件,只需在应用初始化时传入目录路径即可。该中间件会自动拦截以指定前缀开头的请求,并在本地文件系统中查找对应资源。如果找到文件,它直接读取并返回;如果未找到,则继续传递给下游应用处理。

如何配置静态文件服务
配置静态文件服务需要实例化 StaticFiles 对象并将其作为中间件添加到 Starlette 应用中。核心参数是 directory,它指定了静态文件的根目录。此外,还可以设置 html 参数来启用目录浏览或默认文档功能。这种配置方式简单直接,无需编写额外的路由逻辑。

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.staticfiles import StaticFilesMiddleware
# 定义中间件列表,挂载静态文件服务
middleware = [
Middleware(StaticFilesMiddleware, directory="./static")
]
app = Starlette(middleware=middleware)
# 此时访问 /style.css 将尝试读取 ./static/style.css
如何处理静态文件缺失的情况
当请求的静态文件在指定目录下不存在时,StaticFiles 中间件不会抛出异常,而是返回一个标准的 404 Not Found 响应。这种行为确保了静态文件服务不会中断主应用的正常流程。开发者可以通过检查响应状态码来判断文件是否成功加载。如果启用了 HTML 模式且请求的是目录,它可能会尝试返回 index.html 或列出目录内容(取决于具体配置和版本)。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

import os
from starlette.responses import FileResponse
from starlette.routing import Route
from starlette.applications import Starlette
async def homepage(request):
# 模拟一个动态路由,与静态文件共存
return {"message": "Hello World"}
routes = [
Route("/", homepage),
]
app = Starlette(routes=routes, middleware=[
Middleware(StaticFilesMiddleware, directory="./static")
])
# 如果 ./static/nonexistent.css 不存在,请求将返回 404
# 而不会触发 homepage 函数
基于请求路径解析的具体行为
在处理具体请求时,StaticFiles 会根据请求的 URL 路径拼接目录路径进行查找。例如,请求 /assets/main.js 会映射到 ./static/assets/main.js。这种映射是严格的,不支持路径遍历攻击。如果请求路径包含 .. 等危险字符,中间件通常会拒绝请求或忽略这些部分,以确保安全性。实际的文件读取操作发生在中间件的 __call__ 方法中,它使用异步 I/O 提高并发性能。










