Uvicorn不处理静态文件，其职责仅为转发HTTP请求给FastAPI；静态文件服务由FastAPI通过app.mount()挂载StaticFiles子应用实现，需确保路径正确、目录存在且挂载顺序在路由注册之后。
Uvicorn 本身不处理静态文件，别让它背锅
Uvicorn 是 ASGI 服务器，只负责把 HTTP 请求转发给 FastAPI（或其它 ASGI 应用），它没有内置静态文件服务能力。你看到的“Uvicorn 加载静态文件”，其实是 FastAPI 通过 StaticFiles 实现的，Uvicorn 只是忠实地执行了这个子应用的响应逻辑。如果你直接用 uvicorn main:app 启动却访问不到 /static/logo.png，问题一定出在 FastAPI 的挂载配置上，而不是 Uvicorn 参数没加对。
StaticFiles 挂载必须用 app.mount()，不能靠路由装饰器
常见错误是试图用 @app.get("/static/{path:path}") 手动读文件返回——这不仅慢、不安全、不支持缓存头和 Range 请求，还会绕过 StaticFiles 的路径规范化和目录遍历防护。正确方式只有一种：app.mount()。
-
app.mount()注册的是一个 ASGI 子应用，不是普通路由，它能处理路径匹配、目录索引、MIME 类型推断、条件请求等全部细节 - 挂载路径（第一个参数）必须以
/开头，比如"/static"，不能写成"static"或"/static/"（末尾斜杠会干扰子路径匹配） - 本地目录（
directory=）必须是绝对路径，推荐用Path(__file__).parent / "static"构造，避免相对路径在不同工作目录下失效 - 如果要支持单页应用（如 Vue/React 构建产物），务必加
html=True，否则访问/app/会 404，而不是返回index.html
挂载后 404？先检查三件事
绝大多数 404 不是代码写错，而是环境或路径理解偏差：
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 确认文件真实存在且有读权限：运行
ls -l static/style.css，确保不是 IDE 自动隐藏了扩展名或生成了 .DS_Store 干扰 - 确认挂载顺序：
app.mount()必须在所有@app.get()路由注册之后调用，否则会被前面的通配路由（如@app.get("/{path:path}")）提前捕获 - 确认部署时的
root_path：如果你用 Nginx 把/admin代理到后端/，但 FastAPI 内部仍按/static生成资源链接，浏览器实际请求的是/admin/static/xxx，而你的StaticFiles挂在了/static—— 这时候必须初始化 FastAPI 时传root_path="/admin"，否则静态路径拼接全错
生产环境别裸跑 Uvicorn，但静态文件逻辑不变
用 Gunicorn + Uvicorn 组合部署时，StaticFiles 的挂载方式完全一样，不需要改一行代码。Gunicorn 只是进程管理器，Uvicorn 仍是那个 ASGI 服务器，FastAPI 的挂载行为不受影响。唯一要注意的是：静态文件目录路径必须对所有 worker 进程可见，不要用临时目录或用户家目录下未授权的路径；如果用 Docker，确保 static/ 目录已 COPY 进镜像且权限为 1001:1001（Uvicorn 默认用户）。
