FastAPI中StaticFiles路径不生效的根本原因是directory必须为绝对路径；挂载路径（app.mount第一参数）决定URL前缀，需与请求路径一致；生产环境应由Nginx托管静态文件。
FastAPI 里用 StaticFiles 托管文件，但路径不生效？
根本原因是 StaticFiles 的 directory 参数必须是**绝对路径**，相对路径（比如 "./static"）在不同启动位置下会失效。它不自动做 os.path.abspath()，也不读取当前工作目录的上下文。
实操建议：
- 用
Path(__file__).parent / "static"或os.path.join(os.path.dirname(__file__), "static")构造绝对路径 - 启动前先检查路径是否存在：
assert (Path("static").exists())，避免静默失败 - 别把静态目录放在项目根目录外——
StaticFiles默认禁止向上遍历（如../secret.txt），这是安全机制，不是 bug
为什么访问 /static/logo.png 返回 404，但文件明明存在？
常见错误是挂载点（mount path）和实际请求路径没对齐。比如你写了 app.mount("/assets", StaticFiles(directory="static"), name="static")，那真实 URL 就是 /assets/logo.png，而不是 /static/logo.png。
关键点：
立即学习“Python免费学习笔记（深入）”；
-
app.mount()第一个参数是 URL 前缀，和directory内容无关 - 浏览器地址栏输入的路径，必须和 mount 的 prefix 完全匹配（区分大小写、尾部斜杠）
- 如果想用
/static/xxx，就老老实实写app.mount("/static", ...) - 挂载顺序有影响：FastAPI 按代码顺序匹配路由，
StaticFiles应该放在所有 API 路由之后，否则可能被前面的Route拦截
支持中文文件名下载或显示乱码？
问题出在 FastAPI 默认用 filename*（RFC 5987）编码响应头，但部分旧浏览器或命令行工具（如 wget）只认传统 filename。更麻烦的是，Windows 上 Python 的 pathlib.Path.name 在非 UTF-8 locale 下可能返回乱码。
稳妥做法：
- 服务端不做特殊编码，靠浏览器自动解析——现代 Chrome/Firefox/Edge 都没问题
- 若必须兼容老旧环境，手动构造
Content-Disposition头，用urllib.parse.quote编码文件名，但注意只对 filename 部分编码，不要动整个 header 字符串 - 避免在文件名里用控制字符、
\、?等 shell 敏感符号，FastAPI 不做过滤，直接透传给 OS，可能引发OSError: Invalid argument
并发大了，StaticFiles 成瓶颈？
StaticFiles 是纯 Python 实现，同步读文件 + 同步发包，没有用 asyncio.to_thread 或内存缓存，高并发小文件场景下容易卡住事件循环。
能做的有限但有效：
- 开发阶段够用；生产务必用 Nginx 反代静态资源，把
/static/全部甩给它处理 - 如果非得用 FastAPI 直出，至少加个
response_class=FileResponse替代默认行为，它支持stat缓存和 range 请求 - 别用
StaticFiles托管超过几 MB 的单文件（比如视频），它不会流式传输，而是全量读进内存再发，OOM 风险很高
真正麻烦的从来不是怎么写那三行挂载代码，而是路径拼错后查日志看不到任何提示，以及上线前忘了关掉 python -m http.server 占着 8000 端口。
