staticfiles挂载后404主因是路径不匹配：app.mount()的url前缀（如"/static"）必须与html中href路径（如"/static/css/style.css"）完全一致，且directory需用绝对路径（如path(__file__).parent / "static"）并确保大小写、斜杠、工作目录正确。
StaticFiles挂载后访问404，先核对URL前缀和directory路径
绝大多数404不是文件不存在，而是请求路径和挂载配置没对齐。浏览器请求 /static/css/style.css，但代码里写的是 app.mount("/assets", StaticFiles(directory="static"), name="static")，那真实可访问地址其实是 /assets/css/style.css，不是 /static/...。
常见错配点：
-
app.mount("/static", ...)和 HTML 中href="/assets/css/style.css"不一致 -
directory="STATIC"（大写）但实际目录名是static（小写），Linux/macOS 下大小写敏感 -
directory="static/"末尾多斜杠，某些版本会报NotADirectoryError或静默失败 - 启动时工作目录不是项目根目录，导致
directory="static"解析成错误路径
directory必须是绝对路径，否则换位置就失效
FastAPI 的 StaticFiles 不自动做路径补全，"./static" 或 "static" 是相对路径，依赖当前工作目录（os.getcwd()），而 IDE、Docker、systemd 启动时 cwd 往往不同。
正确做法是用绝对路径构造：
-
directory=Path(__file__).parent / "static"（推荐，类型安全） directory=os.path.join(os.path.dirname(__file__), "static")- 挂载前加断言：
assert (Path(__file__).parent / "static").exists()，避免静默失败
别用 check_dir=False 掩盖问题——它只是跳过检查，不解决路径错位。
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
想让 / 自动返回 index.html？必须加 html=True
默认 StaticFiles 是纯文件服务器：请求 / 就去找名为 / 的文件，当然 404；请求 /index.html 才能命中。
开启 SPA 支持要显式启用 HTML 模式：
app.mount("/", StaticFiles(directory="static", html=True), name="static")- 此时访问
/→ 查找static/index.html；访问/admin→ 查找static/admin/index.html - 注意：
html=True仅影响目录请求的 fallback 行为，不影响文件直连（如/logo.png）
挂载顺序和路由冲突常被忽略
app.mount() 是按代码顺序注册的 ASGI 子应用，如果把它写在 @app.get("/...") 路由定义之前，某些通配路径（比如带 {path:path} 的 API）可能提前拦截请求，导致 StaticFiles 根本没机会处理。
务必把 app.mount() 放在所有 @app.get、@app.post 等路由注册之后。
验证是否生效最简单的方法：直接浏览器访问 http://127.0.0.1:8000/static/test.txt（确保该文件真实存在），能下载说明挂载和路径都通了；不能，则问题一定出在前三个环节里。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
