FastAPI Swagger文档空白的根本原因是默认依赖国外CDN资源加载失败，解决方法是下载swagger-ui-bundle.js、swagger-ui.css等离线资源至本地static目录，并通过app.mount挂载静态路由、自定义/docs路由调用get_swagger_ui_html显式指定本地路径。
FastAPI的Swagger文档页面空白或加载失败，基本就是外部CDN资源被拦截或超时——直接把 swagger-ui-bundle.js、swagger-ui.css 等文件下到本地，并让 get_swagger_ui_html() 指向它们，就能彻底解决。
怎么下载 Swagger UI 离线资源
别手动拼 URL 或猜版本，用稳定渠道获取完整 dist 包：
- 从 GitHub 官方 release 下载最新稳定版（如
v5.17.14，截至 2026 年 9 月），解压后取dist/目录下的全部文件 - 或用脚本一键拉取（推荐）：
wget https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui-bundle.js和swagger-ui.css，注意检查 HTTP 状态码是否为 200 - 不要只下 JS/CSS，
favicon-32x32.png和swagger-ui-standalone-preset.js（部分版本需要）也一并下载，否则图标或某些交互会异常
怎么在 FastAPI 中挂载并引用本地静态文件
必须同时完成两件事：静态路由挂载 + 文档函数重写，缺一不可。
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 在
main.py里加静态路由：app.mount("/static", StaticFiles(directory="static"), name="static")，确保static/是项目根目录下的真实路径 - 自定义
/docs路由，调用get_swagger_ui_html()并显式传入本地地址：swagger_js_url="/static/swagger-ui/swagger-ui-bundle.js"、swagger_css_url="/static/swagger-ui/swagger-ui.css" - 注意路径前缀必须带
/，且与app.mount()的挂载路径严格匹配；若挂载为/assets，那 URL 就得写成/assets/swagger-ui/...
为什么不能直接改 fastapi/openapi/docs.py
改源码看似简单，但实际是陷阱：
- 升级 FastAPI 后，你的修改会被覆盖，且不同版本中
get_swagger_ui_html()的参数签名可能变化（比如 1.0.0+ 加了swagger_favicon_url） - 本地开发环境和部署环境 Python 包路径不一致（venv vs system site-packages），容易出现“改了却没生效”的情况
- CI/CD 流程中无法自动同步源码修改，导致测试环境正常、生产环境崩溃
常见报错和对应检查点
如果改完还是白屏或 404，请按顺序排查：
- 浏览器开发者工具 Network 标签页里，看
swagger-ui-bundle.js请求是否返回 200 —— 若是 404，说明directory="static"路径不对，或文件没放对位置 - 控制台报
Uncaught ReferenceError: SwaggerUIBundle is not defined，大概率是 JS 文件损坏或 MIME 类型错误，检查 Nginx/Apache 是否误配了text/plain响应头 - 样式错乱但功能正常？确认
swagger-ui.css已加载，且里面没有引用其他外部字体或图片（新版 Swagger UI 默认已移除 Google Fonts，但旧包可能残留）
最易被忽略的是 favicon 路径和 OpenAPI JSON 的可访问性：即使所有静态资源都本地化了，/openapi.json 这个接口仍需能被浏览器直接请求到，否则 Swagger UI 初始化就卡住。别只盯着 JS/CSS，先 curl 一下 http://localhost:8000/openapi.json 确认返回有效 JSON。
