挂载StaticFiles需确保路径严格一致、目录真实存在且大小写敏感，推荐用绝对路径；HTML模式仅在根挂载时启用以支持SPA路由；使用url_for生成URL更安全。
直接挂载 StaticFiles 就能引入 CSS，但路径错、目录不存在、HTML 模式没开，都会导致 404 或空白样式 —— 这不是代码写错了，而是挂载逻辑没对齐。
挂载路径和前端引用路径必须严格一致
浏览器请求的 URL 前缀（比如 /static/css/style.css）必须和 app.mount() 的第一个参数完全匹配。如果写成 app.mount("/assets", ...)，但 HTML 里仍写 href="/static/css/style.css"，浏览器根本不会发请求到后端静态服务。
-
app.mount("/static", StaticFiles(directory="static"), name="static")→ 前端必须用/static/xxx -
app.mount("/public", StaticFiles(directory="static"), name="static")→ 前端改用/public/xxx - 路径区分大小写，
/Static≠/static - 不要在
directory值末尾加斜杠：directory="static/"会报错或找不到文件
directory 参数必须指向真实存在的本地目录
StaticFiles 启动时默认检查目录是否存在（check_dir=True），如果 directory="static" 但项目根目录下没有这个文件夹，FastAPI 直接启动失败，报错类似 Directory 'static' does not exist。
- 确认目录存在：运行
ls static（macOS/Linux）或dir static（Windows） - 相对路径以当前工作目录为准，不是
main.py所在目录 —— 推荐用绝对路径避免歧义：directory=Path(__file__).parent / "static" - 如果目录确实不存在又不想报错，可设
check_dir=False，但仅用于调试，上线前务必修复
HTML 模式（html=True）只在挂载根路径时有用
如果你把静态文件挂到 "/"（比如 SPA 前端），必须开启 html=True，否则访问 http://localhost:8000/about 这类前端路由时会 404 —— 因为 StaticFiles 默认不处理目录索引。
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
立即学习“前端免费学习笔记（深入）”；
-
app.mount("/", StaticFiles(directory="dist", html=True), name="spa")→ 访问任意路径都 fallback 到index.html -
app.mount("/static", ...)这种带前缀的挂载，html=True几乎无用，因为不会有人去访问/static/some-route这种“伪目录” - 开启
html=True后，StaticFiles会在找不到具体文件时尝试返回index.html，这是 SPA 路由的核心机制
使用 url_for 生成静态资源 URL 更安全
硬编码路径如 href="/static/css/style.css" 容易和挂载点脱节；换成 url_for("static", path="/css/style.css") 可自动适配 name 和挂载路径，尤其适合配合 Jinja2Templates。
- 前提是挂载时指定了
name参数：app.mount("/static", StaticFiles(...), name="static") - 模板中写：
<link rel="stylesheet" href="{{ url_for('static', path='/css/style.css') }}"> -
path值必须以/开头，且是相对于directory的路径，不是完整 URL - 注意：
url_for在纯 HTML 响应中不可用，只适用于TemplateResponse
最容易被忽略的是工作目录和 directory 的关系 —— FastAPI 不关心你的 main.py 在哪，它只认你执行 uvicorn 命令时所在的路径。同一份代码，cd project && uvicorn main:app 和 cd .. && uvicorn project/main:app 下的 directory="static" 指向完全不同位置。
