FastAPI 学习之路（三十八）Static Files

最新推荐文章于 2025-08-05 16:33:48 发布

原创

最新推荐文章于 2025-08-05 16:33:48 发布 · 613 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#fastapi

如果使用前后台不分离的开发方式，那么模版文件中使用的静态文件，比如css/js等文件的目录需要在后台进行配置，以便模版渲染是能够正确读取到这些静态文件的。那么我们如何处理呢？

首先安装依赖

pip install aiofiles

我们看下如何使用

我们定义一个页面，展示一张图片

①：创建两个文件夹static和templates

②：分别放置一个home.html和test.png

其中home.html代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>

<img src="{
  
  { url_for('static',path='/test.png') }}" style="width: 500px;height: 500px">

</body>
</html>

③：我们看下在fastapi中如何使用

from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from fastapi import FastAPI, Reque

最低0.47元/天解锁文章

确定要放弃本次机会？

福利倒计时

: :

立减 ¥

普通VIP年卡可用

立即使用

一起学python吧

关注关注

3
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
分享

复制链接

分享到 QQ

分享到新浪微博

扫一扫
举报

举报

专栏目录

FastAPI（42）- Static Files 静态资源

qq_33801641的博客

09-29

1513

安装 aiofiles pip install aiofiles 个人感想现在都是前后端分离，感觉在 FastAPI 应用程序中直接使用静态资源的可能性不大，只做了解(也不难使用 StaticFiles 访问静态资源 from fastapi import FastAPI from fastapi.staticfiles import StaticFiles from fastapi....

24.FastAPI静态文件

chenhaiy的博客

02-07

5371

24.FastAPI静态文件在FastAPI中，如果需要使用静态文件，可以使用StaticFiles，将它挂载到应用程序中。挂载StaticFiles的方法： app.mount("/static", StaticFiles(directory="static"), name="static") 其中参数： "/static" 是指这个“子应用程序”将被“安装”到的子路径。因此，任何以"/static"开头的路径都将由它处理。 StaticFiles(directory.

参与评论您还未登录，请先登录后发表或查看评论

FastAPI：(14)静态文件，测试

qq_45031509的博客

06-16

1043

本文介绍了FastAPI中的静态文件处理和测试方法。主要内容包括：静态文件挂载：使用app.mount()方法将静态文件目录或子应用挂载到指定路径，实现路径隔离且不影响主应用逻辑。正例展示了如何挂载静态文件夹和子应用，反例则揭示挂载到根路径的潜在问题。静态文件特性：静态文件无需后台处理、内容固定、支持高效缓存，并可直接映射URL访问。通过实例演示了静态资源服务和上传文件处理。测试分类：涉及端到端测试、单元测试和集成测试，为应用质量提供保障。文中强调合理挂载的重要性，并提供了官网子应用文档的访问示例，

FastAPI入门：静态文件、测试、调试

m0_52049533的博客

08-05

466

导入StaticFiles。“挂载”(Mount) 一个 StaticFiles() 实例到一个指定路径。这个 “子应用” 会被 “挂载” 到第一个 “/static” 指向的子路径。因此，任何以"/static"开头的路径都会被它处理。directory=“static” 指向包含你的静态文件的目录名字name=“static” 提供了一个能被FastAPI内部使用的名字。

三周精通FastAPI：31 使用 StaticFiles从目录中自动提供静态文件

skywalk8163的专栏

11-04

1209

¶"挂载" 表示在特定路径添加一个完全"独立的"应用，然后负责处理所有子路径。这与使用APIRouter不同，因为安装的应用程序是完全独立的。OpenAPI和来自你主应用的文档不会包含已挂载应用的任何东西等等。你可以在高级用户指南中了解更多。

FastAPI 学习之路（四十五）WebSockets（二）

mr~li的博客

07-12

859

上一节，我们分享了WebSockets入门的使用方法，本节，我们在原来的基础上，进行深入的演示。在 FastApi学习之路（三十八）Static Files，我们提到了静态文件的使用，我们按照之前的方法，将上一节中的静态代码抽离出来。这样我们的WebSockets就可以带token来做登录了，但是我们的token呢，只是做了简单的校验。肯定是可以的，我们在下次分享的时候将登录退出分享出来。但是我们之前的html代码去调试的时候，发现报错，因为我们需要依靠session或者token。

FastAPI系列教程18：fastapi utils，改造你的FastAPI程序

GeekABC

05-15

1274

本节我们介绍fastapi utils，这是一个细致的实用工具库，它可以帮助我们使用OOP结构来组织路由、服务及数据库模型；同时它也针对sqlalchemy的使用进行了扩展；最后它还提供了一些贴心的小功能如任务调度工具、计时中间件等等。

FastAPI使用教程【更新中】

热门推荐

什么都干的派森

06-27

1万+

二、模板创建 main.py 文件，内容如下三、启动命令 ps：127.0.0.1:8000 127.0.0.1:8000/docs【Swagger UI 提供的api文档】 127.0.0.1:8000/redoc【ReDoc 提供的api文档】代码调用方法 2.指定数据类型的路径参数代码调用方法 3.枚举路径参数代码调用方法 4.匹配所有路径代码调用方法 5.普通传参代码调用方法 6.必备参数代码调用....................................

FastAPI 教程翻译 - 用户指南 33 - 静态文件

人生苦短，我用Python！

06-08

1362

FastAPI 教程翻译 - 用户指南 33 - 静态文件 FastAPI Tutorial - User Guide - Static Files You can serve static files automatically from a directory using StaticFiles. 您可以使用 StaticFiles 从目录自动提供静态文件。 Install aiofiles 安装 aiofiles First you need to install aiofiles: 首先，您需要安装

fastapi_No.19_静态文件

Ethan's Blog

10-29

1623

主要讲解了如何在fastapi中创建静态文件目录

FastAPI 静态文件服务：快速配置与挂载 HTML

敲代码别忘了喝上一杯凉白开。

02-20

952

FastAPI 提供了方便的静态文件服务配置，通过 `StaticFiles` 实现静态资源的挂载。开发者可以将静态文件目录挂载到指定路径，FastAPI 会自动处理文件的请求。这样，所有以 `/static` 开头的请求将被 FastAPI 自动处理，方便访问静态文件如 HTML、CSS、JavaScript 文件等。静态文件服务非常适用于展示页面或提供静态资源支持，且与主应用的 API 接口和文档无关，简洁且高效。

fastapi挂载静态文件夹，RuntimeError: Directory ‘static‘ does not exist

奔跑的坏蜗牛

03-05

1433

fastapi挂载静态文件夹，本地运营正常，上传服务器后，RuntimeError: Directory 'static' does not exist

Python高性能web框架-FastApi教程：(11)静态文件请求

程序员涛哥的博客

12-24

692

在 Web 开发中，需要请求很多静态资源文件（不是由服务器生成的文件），如 css/ijs 和图片文件等。- 这是URL路径前缀，意味着所有以 /static 开头的URL请求都会被这个处理程序处理。这样的配置让你可以方便地管理和提供静态资源，而不需要为每个静态文件都写专门的路由处理程序。- 这是FastAPI的一个方法，用于将某个路径挂载到特定的处理程序上。如果你在 statics 文件夹中有一个图片文件 logo.png。- 这创建了一个静态文件处理程序。

【FastAPI 】FastAPI 模板：提供静态文件

CITYDATA

08-20

761

在哪里找到您的静态文件并将它们挂载在特定路径下。应用程序都是必不可少的，因为它们有助于创建用户界面并增强用户体验。静态文件是不经常更改的资产，并按原样交付给客户端。以提供静态文件的基础知识，并提供了一些演示来帮助您入门。请随意尝试这些示例并扩展它们以适合您的特定用例。模板中的文件，您可以创建一个丰富的交互式。创建一个简单的路由来提供引用静态文件的。可以轻松提供这些文件并将其集成到您的。应用程序中，从而提供丰富的用户体验。假设您有一个想要作为静态文件提供的。您可以通过提供引用动态属性的静态。

西北乱跑娃 --- fastapi路由惯用写法与静态文件夹设置

西北乱跑娃的博客

10-02

904

pip install fastapi[all] pip install aiofiles from fastapi import FastAPI, Request, requests from fastapi.responses import JSONResponse, HTMLResponse import uvicorn from fastapi.staticfiles import StaticFiles import asyncio app = FastAPI() app.mount("/st

FastAPI静态文件映射到网页

qq_41081716的博客

03-10

1010

安装了FastAPI 和 Uvicorn：pip install fastapi uvicorn。同样，你可以根据实际情况修改路径和路由。然后，打开浏览器访问。

12.FastAPI静态文件配置

m0_49501453的博客

11-28

1909

12.静态文件配置在主运行文件下配置（run.py） # 导包 from fastapi.staticfiles import StaticFiles # mount表示将某个目录下一个完全独立的应用挂载过来，这个不会在API交互文档中显示， path = '/static'表示静态文件url路径 app.mount(path='/static', app=StaticFiles(directory='./coronavirus/static'), name='static') # .moun

FastAPI学习（六）——bootstrap前端框架和static静态文件路径的使用

weixin_43605788的博客

03-04

6246

文章目录目录结构：post_test_5.py：index.html:signin.html注意：完整代码：目录结构：上代码： post_test_5.py： # -*- coding: UTF-8 -*- from fastapi import FastAPI, Form from starlette.requests import Request from starlette.stati...

西北乱跑娃 -- fastapi设置静态文件以及跨域访问

西北乱跑娃的博客

04-15

1076

import sys sys.path.append('../') from fastapi import FastAPI, Request from fastapi.responses import HTMLResponse, JSONResponse from fastapi.middleware.cors import CORSMiddleware import uvicorn from fastapi.staticfiles import StaticFiles import asyncio a

fastapi.mount

最新发布

10-15

<think>我们被要求详细解释FastAPI中的mount功能，包括其使用方法、作用以及注意事项。同时，需要参考提供的引用内容，并自然地添加引用标识。根据引用内容，我们可以总结如下： 1. 挂载（mount）的作用是将一个完整的独立应用程序（可以是静态文件目录、另一个FastAPI应用、Starlette应用或任何ASGI/WSGI应用）添加到主应用的特定路径下，形成一个整合的应用。[^1][^2][^3] 2. 挂载与使用APIRouter不同，因为挂载的应用程序是完全独立的，主应用的OpenAPI文档不会包含挂载应用的内容。[^2][^3] 3. 挂载常用于静态文件服务（如使用StaticFiles）或者将多个独立的FastAPI应用组合起来（每个子应用有自己的文档）。[^2][^3][^4] 4. 挂载的示例：主应用可以挂载一个静态文件服务（StaticFiles）到路径"/static"，这样所有以"/static"开头的请求都会由这个静态文件应用处理。[^2][^4]同样，也可以挂载另一个FastAPI子应用，比如主应用挂载一个子应用到"/subapi"，那么访问"/subapi"及其子路径的请求都会交给子应用处理。[^3] 下面我们将详细展开： ### 📌 FastAPI 挂载（Mount）详解 #### 1. 什么是挂载？挂载（Mount）是指将一个独立的WSGI或ASGI应用程序附加到主FastAPI应用的特定路径下。这个被挂载的应用将负责处理所有以该路径开头的请求。挂载的应用与主应用完全独立，包括文档（如OpenAPI/Swagger）也不会相互干扰。[^2][^3] #### 2. 挂载的作用 - **整合多个独立应用**：例如，将多个FastAPI子应用（每个子应用可能由不同团队开发）组合成一个整体。[^1][^3] - **提供静态文件服务**：快速设置静态文件（如图片、CSS、JavaScript）的访问路径，无需编写额外路由。[^2][^4] - **集成第三方应用**：可以挂载任何符合WSGI或ASGI标准的应用，如Dash应用、Flask应用等。 #### 3. 使用方法 ##### 3.1 挂载静态文件使用`StaticFiles`类来挂载静态文件目录： ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app = FastAPI() # 将静态文件目录static挂载到/app/static路径 app.mount("/static", StaticFiles(directory="static"), name="static") ``` - `directory`：静态文件所在的本地目录。 - `name`：挂载应用的名称（FastAPI内部使用，可选）。 - 访问示例：`http://localhost:8000/static/image.png` 将返回`static/image.png`文件。[^4] ##### 3.2 挂载另一个FastAPI应用假设有两个独立的FastAPI应用，主应用和子应用： ```python # 主应用 from fastapi import FastAPI app = FastAPI() @app.get("/main") def read_main(): return {"message": "Main app"} # 子应用 subapp = FastAPI() @subapp.get("/sub") def read_sub(): return {"message": "Sub app"} # 将子应用挂载到主应用的"/subapp"路径下 app.mount("/subapp", subapp) ``` - 此时，访问主应用的`/main`路径由主应用处理。 - 访问`/subapp/sub`路径则由子应用处理。[^3] ##### 3.3 挂载其他ASGI/WSGI应用同样方法也可以挂载Starlette应用或其他ASGI应用： ```python from fastapi import FastAPI from starlette.applications import Starlette app = FastAPI() # 创建一个Starlette应用 starlette_app = Starlette() @starlette_app.route("/star") async def starlette_endpoint(request): return {"message": "Starlette app"} app.mount("/external", starlette_app) ``` #### 4. 注意事项 1. **路径独立性**：挂载的应用处理所有以指定路径开头的请求，因此主应用不会处理这些请求。[^2] 2. **文档隔离**：主应用的OpenAPI文档不会包含挂载应用的路由，挂载的子应用如果有自己的文档（如FastAPI子应用），则可以通过其独立路径访问（如`/subapi/docs`）。[^3] 3. **路径匹配优先级**：当同时存在多个挂载点时，FastAPI会按照挂载的先后顺序进行匹配（从最长的路径前缀开始？实际上，由于挂载是精确到路径前缀的，所以不会冲突，但要注意挂载路径不要重叠，比如先挂载`/static`，再挂载`/static/images`会导致后者被忽略？实际上，挂载是前缀匹配，且按添加顺序匹配，但通常我们确保挂载路径不重叠）。 4. **中间件影响**：挂载的应用可以有自己的中间件，但主应用的中间件不会自动作用于挂载的应用（除非在挂载前添加的全局中间件，因为中间件作用于整个ASGI树）。[^3] 然而，需要注意的是，在主应用上添加的中间件会作用于所有请求（包括挂载的子应用），因为挂载是主应用的一部分。而子应用自己的中间件只作用于子应用的请求。 5. **静态文件服务安全问题**：使用`StaticFiles`时，确保目录路径安全，避免暴露敏感文件。 #### 5. 示例：整合静态文件与子应用 ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app = FastAPI() subapp = FastAPI() # 主应用路由 @app.get("/") def home(): return "Main App" # 子应用路由 @subapp.get("/hello") def hello(): return "Hello from Sub App" # 挂载子应用 app.mount("/sub", subapp) # 挂载静态文件 app.mount("/assets", StaticFiles(directory="assets"), name="assets") ``` #### 6. 工作流程 ```mermaid graph LR A[主FastAPI应用] --> B[挂载点1: /sub] A --> C[挂载点2: /assets] B --> D[子应用处理所有/sub/*请求] C --> E[StaticFiles处理所有/assets/*请求] ``` ### 常见问题 1. **挂载与APIRouter的区别？** APIRouter用于模块化同一个FastAPI应用内的路由，而挂载用于集成完全独立的应用（包括静态文件服务、其他框架应用等）。挂载的应用不共享主应用的OpenAPI文档。[^2][^3] 2. **如何为挂载的子应用添加中间件？** 在子应用上直接添加中间件（如果子应用是FastAPI或Starlette应用）： ```python from fastapi.middleware.cors import CORSMiddleware subapp.add_middleware(CORSMiddleware, ...) ``` 3. **静态文件挂载后前端如何访问？** 假设挂载路径为`/static`，文件`logo.png`在`static`目录下，则前端通过`/static/logo.png`访问。[^4] 4. **能否挂载多个静态文件目录？** 可以，挂载到不同路径即可： ```python app.mount("/images", StaticFiles(directory="images"), name="images") app.mount("/docs", StaticFiles(directory="pdfs"), name="pdfs") ``` §§相关问题§§ 1. 如何在挂载的子应用中使用中间件？ 2. 挂载静态文件时如何设置缓存控制？ 3. 如何挂载一个Flask应用到FastAPI？ 4. 挂载的应用能否共享主应用的状态（如数据库连接池）？ 5. 如何解决挂载路径冲突问题？ </think>### 📌 FastAPI 挂载（Mount）详解挂载（Mount）是 FastAPI 的核心功能之一，用于将**独立的子应用**集成到主应用中，使其处理特定路径下的所有请求。与 `APIRouter` 不同，挂载的应用完全独立，拥有自己的路由、中间件和文档系统。 --- #### ️ 作用与核心特性 1. **应用整合** 将静态文件服务、其他 FastAPI 应用或任意 ASGI/WSGI 应用（如 Starlette、Flask）挂载到主应用： ```python app.mount("/subapp", subapp) # 子应用处理所有 /subapp/* 请求[^3] ``` 2. **静态文件服务** 快速托管 CSS/JS/图片等静态资源： ```python from fastapi.staticfiles import StaticFiles app.mount("/static", StaticFiles(directory="static"), name="static")[^2][^4] ``` 3. **文档独立性** 挂载的子应用拥有独立的 OpenAPI 文档： - 主应用文档：`http://localhost:8000/docs` - 子应用文档：`http://localhost:8000/subapp/docs`[^3] --- #### 🚀 使用方法详解 ##### 场景1：挂载静态文件 ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app = FastAPI() # 挂载静态资源目录 app.mount("/static", StaticFiles(directory="static_files"), name="static"[^2]) # 前端访问示例：/static/logo.png -> static_files/logo.png ``` ##### 场景2：挂载子应用 ```python # ---------- 主应用 main.py ---------- from fastapi import FastAPI from subapp import subapp # 导入子应用 app = FastAPI() app.mount("/api/v1", subapp) # 挂载到 /api/v1 路径[^3] # ---------- 子应用 subapp.py ---------- from fastapi import APIRouter subapp = APIRouter() @subapp.get("/users") def get_users(): # 实际路径：/api/v1/users return [{"id": 1, "name": "Alice"}] ``` ##### 场景3：挂载第三方应用 ```python from starlette.applications import Starlette from fastapi import FastAPI # 创建 Starlette 应用 starlette_app = Starlette() @starlette_app.route("/external") async def external_endpoint(request): return {"service": "External API"} # 挂载到主应用 app = FastAPI() app.mount("/external", starlette_app) # 处理 /external/* ``` --- #### ️ 注意事项 1. **路径匹配规则** - 挂载路径按**添加顺序匹配**（类似中间件） - 避免路径重叠：`/static` 和 `/static/images` 会冲突[^2] 2. **文档隔离性** - 主应用的 OpenAPI 文档**不会包含**挂载的子应用路由[^3] - 如需统一文档，改用 `APIRouter` 3. **中间件作用域** - 主应用的中间件**会影响**挂载的子应用 - 子应用可单独添加中间件： ```python subapp.add_middleware(CORSMiddleware) # 仅作用于子应用 ``` 4. **静态文件安全** - 禁用目录遍历：`StaticFiles` 默认不允许访问上级目录 - 自定义 404 响应： ```python app.mount("/static", StaticFiles(directory="static", html=True), name="static") ``` --- #### 🔍 工作流程 ```mermaid graph LR A[客户端请求 /subapp/data] --> B[主FastAPI应用] B --> C{路径匹配} C -->|匹配 /subapp| D[挂载的子应用] D --> E[处理 /data 路由] E --> F[返回响应] ``` ---