Python Web框架-FastAPI教程-StaticFiles()详细说明 作者:马育民 • 2026-05-24 15:44 • 阅读:10001 # 介绍 `StaticFiles` 是 FastAPI/Starlette 提供的 **异步静态文件服务类**,专门用来托管 HTML、JS、CSS、图片等静态资源,底层基于 `aiofiles` 实现非阻塞 I/O,性能高。 需要搭配 [app.mount()](https://www.malaoshi.top/show_1GW3Mz7HdtD6.html "app.mount()") 挂载使用 # 依赖 `fastapi[standard]` 已自带 ``` pip install aiofiles ``` # 导入 ```python # 推荐 from fastapi.staticfiles import StaticFiles # 等价(FastAPI 基于 Starlette) from starlette.staticfiles import StaticFiles ``` # 构造函数参数 ```python StaticFiles( *, directory=None, # 静态文件目录(必填) packages=None, # 从Python包加载静态文件 html=False, # 是否启用SPA模式(关键) check_dir=True, # 启动时检查目录是否存在 follow_symlink=False # 是否跟随符号链接 ) ``` ### 1. `directory`(必填) - 类型:`str`/`Path`,相对/绝对路径均可。 - 作用:指定静态文件所在目录。 - 示例: ```python StaticFiles(directory="static/dist") # Vue打包目录 ``` ### 2. `html`(重点,SPA必备) - 类型:`bool`,默认 `False`。 - 作用: - `html=True`:访问目录或不存在路径时,自动返回 `index.html`(解决Vue/React路由刷新404)。 - `html=False`:仅返回真实文件,目录/不存在路径返回404。 - Vue场景必须设为 `True`。 ### 3. `packages`(不常用) - 类型:`list`,用于从Python包内加载静态资源。 - 示例:`packages=["fastapi"]`,加载包内 `static` 目录。 ### 4. `check_dir` - 类型:`bool`,默认 `True`。 - 作用:启动时校验 `directory` 是否存在,不存在则抛异常。 ### 5. `follow_symlink` - 类型:`bool`,默认 `False`。 - 作用:是否允许通过符号链接访问外部文件(生产环境建议关闭)。 # app.mount() 挂载用法 ```python app.mount( path="/", # 访问前缀 app=StaticFiles(...), # 静态文件实例 name="static" # 内部标识名 ) ``` ### 参数说明 - `path`:URL前缀,如 `/static` 或 `/`(根路径)。 - `name`:FastAPI内部用,用于反向URL解析,可自定义。 # 完整示例 ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles from fastapi.responses import FileResponse app = FastAPI() # 挂载Vue打包目录到根路径 app.mount( path="/", app=StaticFiles(directory="static/dist", html=True), name="static" ) # 兜底(可选,增强兼容性) @app.get("/") async def index(): return FileResponse("static/dist/index.html") ``` --- # 工作原理 1. 启动时:`check_dir=True` 校验目录存在性。 2. 请求匹配: - 访问 `http://localhost:8000/js/app.js` → 映射到 `static/dist/js/app.js`。 - 访问 `http://localhost:8000/about`(Vue路由)→ 文件不存在 → `html=True` → 返回 `index.html`,由Vue路由处理。 3. 响应:异步读取文件,自动设置正确的 `Content-Type`。 --- # 常见问题与避坑 ### 1. 404错误 - 原因:`directory` 路径错误、文件不存在、挂载前缀不匹配。 - 解决: - 用绝对路径测试:`directory="/path/to/static/dist"`。 - 确保Vue打包时 `base: "./"`(`vite.config.js`)。 ### 2. 路由刷新404 - 原因:未设置 `html=True`。 - 解决:`StaticFiles(directory="...", html=True)`。 ### 3. 静态资源与API路由冲突 - 原因:根路径 `/` 同时挂载静态文件和API路由。 - 解决: - 静态文件挂载到 `/static`,API用 `/api` 前缀。 - 或调整路由顺序,API路由优先。 --- # 与Nginx对比 - FastAPI `StaticFiles`:开发/小型项目足够,部署简单,无需额外组件。 - Nginx:生产环境高性能,支持缓存、压缩、负载均衡,适合高并发场景。 --- # 总结 `StaticFiles` 是 FastAPI 托管静态资源的核心工具,**`directory` 指定目录、`html=True` 支持SPA路由**是Vue3项目的关键配置。开发环境直接用,生产环境可搭配Nginx提升性能。 原文出处:http://www.malaoshi.top/show_1GW3MyuMpxH6.html