Python Web框架-FastAPI教程-StaticFiles()详细说明-马育民老师

# 介绍

`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://malaoshi.top/show_1GW3MyuMpxH6.html