挂载StaticFiles时路径必须严格对齐URL前缀，大小写敏感、末尾斜杠不可多；directory须为真实存在的绝对路径，挂载须在app=FastAPI()之后、uvicorn.run()之前且仅一次；HTML中引用CSS须用完整绝对路径如"/static/css/style.css"；SPA场景下仅根路径挂载需启用html=True以fallback至index.html。
挂载 StaticFiles 时路径必须严格对齐
浏览器请求的 URL 前缀（比如 /static/css/style.css）必须和 app.mount() 的第一个参数完全一致，大小写敏感、末尾斜杠也不能多。常见错误是挂载了 app.mount("/static", StaticFiles(directory="static"))，但 HTML 里写 href="css/style.css"——这会发请求到根路径下的 /css/style.css，FastAPI 根本没映射这个前缀，直接 404。
确保目录真实存在：如果 directory="static"，就运行 ls static（macOS/Linux）或 dir static（Windows）确认；相对路径以启动命令所在目录为准，不是 main.py 所在目录——更稳妥的做法是用绝对路径：directory=Path(__file__).parent / "static"。
- 挂载代码必须放在
app = FastAPI()之后、uvicorn.run()之前，且只执行一次 - 不要重复挂载多个
StaticFiles实例（比如分别挂/css和/js），容易路由冲突 -
directory值末尾不能带斜杠，"static/"会导致报错或文件找不到
HTML 中引用 CSS 必须用完整绝对路径
如果你挂载的是 app.mount("/static", ...)，那所有前端引用都得以 /static/ 开头。硬编码写法最直接：<link rel="stylesheet" href="/static/css/style.css">。别写成 css/style.css 或 ./css/style.css，这些是相对路径，浏览器按当前 URL 解析，极大概率错位。
如果用 Jinja2 模板，推荐用 {{ url_for('static', path='/css/style.css') }}——但注意两点：path 参数值必须以 / 开头；模板渲染时要传入 request 对象，否则 url_for 调用失败。
立即学习“前端免费学习笔记（深入）”；
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 静态文件修改后无需重启服务，但浏览器可能缓存旧版本，调试时建议禁用缓存或手动强制刷新（
Cmd+Shift+R/Ctrl+F5） - 挂载前缀统一用
/static，避免用/assets或/public等非常规路径，减少后期模板迁移成本
自定义 Swagger 文档 CSS 不能走默认路由
想给 FastAPI 自动生成的 /docs 页面加样式？先关掉默认文档路由：app = FastAPI(docs_url=None, redoc_url=None)。只要 docs_url 或 redoc_url 任一开启，FastAPI 就走内置 HTML 模板，你挂的 CSS 根本不会加载。
关掉之后，自己注册路由，调用 get_swagger_ui_html 并传入 swagger_css_url（比如 "/static/css/swagger-custom.css"），同时必须显式指定 swagger_js_url 和 openapi_url，否则 JS/CSS 版本不匹配，UI 可能白屏。
- 自托管 CSS 文件需提前挂载好
StaticFiles，路径与swagger_css_url值严格对应 - CSS 选择器优先级必须压过 Swagger 自带的千行样式，常用技巧是加
!important或用更具体的选择器（如.swagger-ui .topbar而非单纯.topbar） - 改完 CSS 后务必清浏览器缓存，否则常出现“明明改了却没变”的假象
SPA 场景下要注意 StaticFiles 的 html 参数
如果你把前端构建产物（如 Vite 的 dist 目录）整个挂到根路径做 SPA，比如 app.mount("/", StaticFiles(directory="dist", html=True), name="spa")，那就必须加 html=True。否则访问 /user/profile 这类前端路由时，StaticFiles 找不到对应文件，直接返回 404，而不是 fallback 到 index.html 让前端路由接管。
但如果是挂到带前缀的路径（如 /static、/assets），html=True 几乎无用，因为没人会去访问 /static/some-route 这种伪目录。
-
html=True仅在挂载点为"/"且项目是 SPA 时才需要 - 启用后，
StaticFiles会在找不到具体文件时尝试返回index.html，这是 SPA 路由的核心机制 - 别在非根挂载场景下误开
html=True，它不会带来额外好处，反而可能掩盖路径配置问题
