介绍

StaticFiles 是 FastAPI/Starlette 提供的 异步静态文件服务类，专门用来托管 HTML、JS、CSS、图片等静态资源，底层基于 aiofiles 实现非阻塞 I/O，性能高。

需要搭配 app.mount() 挂载使用

依赖

fastapi[standard] 已自带

pip install aiofiles

导入

# 推荐
from fastapi.staticfiles import StaticFiles

# 等价（FastAPI 基于 Starlette）
from starlette.staticfiles import StaticFiles

构造函数参数

StaticFiles(
    *,
    directory=None,      # 静态文件目录（必填）
    packages=None,        # 从Python包加载静态文件
    html=False,           # 是否启用SPA模式（关键）
    check_dir=True,       # 启动时检查目录是否存在
    follow_symlink=False  # 是否跟随符号链接
)

1. `directory`（必填）

类型：str/Path，相对/绝对路径均可。
作用：指定静态文件所在目录。

示例：

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() 挂载用法

app.mount(
    path="/",                # 访问前缀
    app=StaticFiles(...),   # 静态文件实例
    name="static"            # 内部标识名
)

参数说明

path：URL前缀，如 /static 或 /（根路径）。
name：FastAPI内部用，用于反向URL解析，可自定义。

完整示例

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")

工作原理

启动时：check_dir=True 校验目录存在性。
请求匹配：
- 访问 http://localhost:8000/js/app.js → 映射到 static/dist/js/app.js。
- 访问 http://localhost:8000/about（Vue路由）→ 文件不存在 → html=True → 返回 index.html，由Vue路由处理。
响应：异步读取文件，自动设置正确的 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提升性能。

原文出处：/show_1GW3MyuMpxH6.html

介绍

依赖

导入