在实际的后端开发里明明本地开发环境跑得好好的 FastAPI 项目一旦部署到内网服务器打开/docs页面就只剩一片空白控制台里刷满了红色报错。这个问题的概率非常高而且几乎每个进入内网环境的团队都会踩上一次。这篇文章就专门来拆解这个现象的根因并给出几套能直接落地的离线解决方案包括具体的配置步骤和完整的静态资源导入方法。先说结论/docs页面是 Swagger UI它本身没问题问题出在浏览器加载它所需的 JS、CSS 资源时默认去外网 CDN 拉文件而你的内网环境根本访问不到外网所以页面就崩了。1. 为什么内网环境docs文档必定出问题1.1/docs页面背后的加载机制FastAPI 的交互式 API 文档页面使用的是 Swagger UI这是一个纯前端的组件。当你在浏览器里访问/docs时FastAPI 返回的是一个 HTML 页面这个页面本身很简单但它在浏览器端运行时还需要动态加载以下几个核心资源Swagger UI 的 JavaScript 文件Swagger UI 的 CSS 样式文件用于代码高亮的第三方库一份名为swagger-ui-config的配置对象用来告诉 Swagger UI 从哪里获取 API 的 JSON 数据FastAPI 在生成这个 HTML 页面时背后调用的是框架自带的get_swagger_ui_html函数而在这个函数里它把这些静态资源的地址默认指向了公共 CDN。具体来说官方默认使用的是https://cdn.jsdelivr.net/npm/swagger-ui-dist5/swagger-ui-bundle.js这类外链地址。这个过程就好比你做了一个网页网页里引用了https://example.com/a.css但对方服务器在内网访问不了example.com那么你的网页自然渲染不出样式。1.2 本地正常、内网不行的真正区别很多人在本地开发时根本发现不了这个问题因为开发机的网络是通的浏览器随时可以从 CDN 拉取资源。但一到内网部署环境情况就完全不同了。要注意的是这里说的内网离线不是指服务器完全没有网络而是指“运行浏览器的客户端无法访问公网 CDN”。比如我遇到过的一种典型拓扑FastAPI 部署在机房的 Linux 服务器上这个服务器本身能访问外网比如要拉取系统包但使用人员坐在办公位办公网络只能访问内网服务器上不了公网。这种情况服务器能上网但浏览器所在的电脑不能所以照样白屏。还有一种更严格的场景整套系统部署在物理隔离的网段里服务器和客户端都完全离线所有依赖都要提前打包好。无论哪种场景/docs页面白屏的核心原因都是同一个浏览器拿不到 HTML 里引用的外部静态资源。1.3 先别急着改造确认三件事在动手改造之前我的建议是先花两分钟确认几个事实避免做无用功。打开/docs页面的浏览器控制台F12切到 Network网络标签页刷新页面看看到底哪些请求失败了。你会看到类似https://cdn.jsdelivr.net/npm/swagger-ui-dist5/swagger-ui-bundle.js的请求状态是 failed 或者 pending 超时。这一步能帮你百分百确认问题根源。再看看 FastAPI 的启动日志如果应用本身报错日志里会有 traceback。通常这种情况应用日志是干净的问题完全出在浏览器端。确认/docs这个路由本身能被访问到而不是被上层网关比如 Nginx、Kong拦截了。这一步可以通过 curl 命令快速验证curl -I http://127.0.0.1:8000/docs返回 200 就说明路由没问题问题确实在静态资源加载环节。确认了这三件事就可以进入解决方案阶段了。2. 方案选型为什么优先推荐本地化静态资源2.1 三个方向的对比解决思路大致有三个方向但效果差异很大方向一修改 CDN 地址比如从 jsdelivr 换成 unpkg。这种做法只治标不治本因为 unpkg、字节跳动 CDN 这些也都属于外网。即使换一个更快的 CDN内网客户端访问不到就是访问不到一点办法也没有所以这个方案本质上是无效的。方向二在服务器上用反向代理转发 CDN 请求。比如在 Nginx 里配置一条规则把对cdn.jsdelivr.net的请求转发到内部的静态资源服务器。这个方案能行但有一个前提所有访问者的浏览器请求必须经过这台 Nginx。如果 FastAPI 在某些场景下被直接访问或者存在多级代理这个方案就容易漏配置而且排查起来很痛苦。另外这个方案要求 Nginx 这台代理服务器本身能访问到外部 CDN否则代理也没有源头可以去拉取。方向三把 Swagger UI 的静态文件下载到本地由 FastAPI 自己作为静态文件服务器来提供这些资源。这是最彻底、最可控的做法。资源文件跟着应用走不需要额外部署 Nginx不需要外网不依赖任何公网基础设施。无论是单机部署还是内网集群只要应用能跑起来/docs就能正常显示。这也是我最终给团队推荐并落地验证过的方案。2.2 离线资源方案的具体逻辑这个方案的核心逻辑是让/docs页面 HTML 中引用的资源路径从https://cdn.jsdelivr.net/...变成/static/swagger-ui/...这样的本地相对路径。FastAPI 本身提供了StaticFiles支持可以直接把某个目录挂载为静态资源目录。所以我们的做法就是在本地有网的机器上下载完整的 Swagger UI 静态文件包。将下载好的文件放到 FastAPI 项目的静态目录下比如static/swagger-ui/。在 FastAPI 应用里注册这个静态目录。重写/docs路由不再使用框架默认的get_swagger_ui_html而是自己构造一个 HTML 响应把静态资源地址指向本地路径。整个过程不需要安装任何额外的第三方包只依赖 FastAPI 自带的fastapi.staticfiles和starlette.responses干净利落。2.3 需要提前准备的文件清单Swagger UI 官方发布的是 npm 包里面包含多个文件。实际离线化改造时你并不需要把整个 npm 包几百个文件全放进去只需要确保以下核心文件完整即可文件名作用必选swagger-ui-bundle.jsSwagger UI 的核心逻辑包含所有组件、交互代码必选swagger-ui.css页面整体样式必选swagger-ui-standalone-preset.js增强功能预设比如扩展的显示布局强烈推荐favicon-32x32.png/favicon-16x16.png浏览器标签页的小图标可选另外如果你希望控制页面的语言或个性化配置也可以准备一份swagger-initializer.js或直接在 HTML 里写配置后续我会展开。3. 实操过程手把手实现/docs离线化3.1 第一步下载 Swagger UI 离线资源包这个步骤需要在一台能访问公网的机器上完成。我建议直接用 npm 下载而不是去官网手动点文件因为 npm 包结构完整版本明确便于后续维护。# 创建项目目录并初始化 package.json如果没有的话 mkdir fastapi-offline-docs cd fastapi-offline-docs # 使用 npm 下载 swagger-ui-dist 指定版本 npm init -y npm install swagger-ui-dist5执行完成后文件会出现在node_modules/swagger-ui-dist/目录下。你不需要把整个node_modules目录塞进项目只需要复制需要的文件出来mkdir -p static/swagger-ui cp node_modules/swagger-ui-dist/swagger-ui-bundle.js static/swagger-ui/ cp node_modules/swagger-ui-dist/swagger-ui.css static/swagger-ui/ cp node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js static/swagger-ui/ cp node_modules/swagger-ui-dist/favicon-32x32.png static/swagger-ui/ cp node_modules/swagger-ui-dist/favicon-16x16.png static/swagger-ui/如果你没有 Node.js 环境也可以直接从 jsdelivr CDN 的页面下载对应文件只要文件名和内容一致就行。不过这样比较繁琐还是npm一条命令省心。3.2 第二步FastAPI 应用里注册静态资源并重写文档路由下面是完整的main.py示例。我在实际项目中使用的就是这套代码可以直接套用from fastapi import FastAPI from fastapi.responses import HTMLResponse from fastapi.staticfiles import StaticFiles app FastAPI(docs_urlNone, redoc_urlNone) # 关闭默认文档路由 # 挂载静态资源目录 app.mount(/static, StaticFiles(directorystatic), namestatic) # 自定义 /docs 页面指向本地静态资源 app.get(/docs, include_in_schemaFalse) async def custom_docs(): return HTMLResponse( !DOCTYPE html html head link typetext/css relstylesheet href/static/swagger-ui/swagger-ui.css link relicon typeimage/png href/static/swagger-ui/favicon-32x32.png sizes32x32 / link relicon typeimage/png href/static/swagger-ui/favicon-16x16.png sizes16x16 / titleAPI Documentation/title /head body div idswagger-ui/div script src/static/swagger-ui/swagger-ui-bundle.js/script script src/static/swagger-ui/swagger-ui-standalone-preset.js/script script window.onload function() { const ui SwaggerUIBundle({ url: /openapi.json, dom_id: #swagger-ui, deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: StandaloneLayout }); window.ui ui; }; /script /body /html , status_code200 )这段代码里有几个关键点需要重点说明为什么给FastAPI传docs_urlNone和redoc_urlNone因为 FastAPI 创建应用实例时如果不传这两个参数它会自动注册/docs和/redoc两个路由。我们手动注册的/docs路由会和默认的冲突所以必须先关掉默认路由再自己定义。redoc_url同样处理因为 ReDoc 页面也存在同样的 CDN 问题。如果你不需要 ReDoc传redoc_urlNone直接禁用即可。为什么用url: /openapi.json而不是直接写死一个 JSON 内容Swagger UI 的url参数可以是一个具体的 OpenAPI 规格文件地址。FastAPI 自带/openapi.json路由会动态生成当前应用所有接口的 OpenAPI 规范。这样写的好处是以后你新增接口、修改参数/docs页面里的内容会自动跟着更新不用手动维护任何东西。3.3 第三步启动服务并验证写完代码后启动 FastAPI 服务uvicorn main:app --host 0.0.0.0 --port 8000然后浏览器访问http://内网IP:8000/docs。验证时逐个检查下面这些点页面能正常渲染出 Swagger UI 的界面能看到 GET、POST 等接口列表。控制台无红色报错资源加载全部显示 200。点击接口点击 Try it out 按钮能正常发出请求并看到响应。再检查一下/openapi.json是否能正常访问确认文档数据源没有问题。如果以上都通过说明离线化改造成功了。3.4 版本锁定与升级注意事项在生产环境一定要把 Swagger UI 的资源版本锁定。比如在上面例子中我用的是swagger-ui-dist5如果哪天有人手痒在服务器上重新npm install可能就升级到了一个不兼容的新版本页面表现可能发生细微变化。建议把版本号精确写死例如swagger-ui-dist5.17.14。升级时也要注意先在有网的开发机上验证新版本文件能正常工作再拷贝到内网环境。不要直接在离线服务器上猜测式地替换文件否则出了问题很难排查因为你连在线调试 JS 的能力都可能受限。4. 常见问题与排查技巧实录4.1 关键路由被/static前缀覆盖导致访问 404这是最容易踩的坑。有人会把静态目录挂载为app.mount(/, StaticFiles(...))这样确实能提供静态文件但会覆盖掉app上所有其他路由导致/docs、/openapi.json全部失效接口调用也全部 404。正确做法是把静态目录挂载到一个独立的前缀下比如/static或者你自定义的其他路径比如/assets。mount操作相当于内置了一个独立的子应用它的路由匹配优先级和普通路由不同。为了安全起见不要让它霸占根路径/。如果你真的想用根路径得使用StaticFiles(htmlTrue)还得把所有 API 路由定义在挂载之前并且挂载时带一个明确的子路径。反正我建议直接避开用/static最省心。4.2 Nginx 反向代理下/docs资源 404 或 403在内网环境中FastAPI 应用前面往往还有一层 Nginx 做反向代理和端口转发。如果docs页面能打开但页面里的资源加载 404那多半是 Nginx 的代理规则没有覆盖/static路径。假设你的 Nginx 配置是这样的location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }如果/static请求也走location /理论上会被代理到 FastAPI。但如果你对/docs做了专门的 location 处理却忘了给/static加上同样的处理就会出问题。另外proxy_pass末尾是否带/也可能影响结果稍不留神就会踩坑。我实际遇到过的情况是Nginx 配置里对/的代理用了一个统一的 upstream但对静态文件路径开启了缓存模块导致缓存目录权限不对静态文件返回 403。排查思路就是看 Nginx 的 error.log不要只盯着 FastAPI 的日志。4.3/docs能打开但页面空白且控制台报错SwaggerUIBundle is not defined这个报错说明 HTML 已经加载了但swagger-ui-bundle.js没有成功执行。通常有两种原因JS 文件本身 404浏览器没拿到脚本内容。拿到 JS 文件了但内容不完整比如从 CDN 复制时没有复制完整或者文件被文本编辑器打开保存时自动转换了编码格式。特别是第二种情况很隐蔽。JS 文件一定要用二进制方式传输不要用记事本或 IDE 打开再另存为。我见过一个同事用编辑器打开.js文件后编辑了一下保存完就坏了整个文件末尾少了一段。排查时很崩溃因为文件体积看起来正常但浏览器就是解析不了。正确的验证方式是在服务器上对比本地文件大小是否与在线版一致。也可以在浏览器直接访问该 JS 文件的 URL查看响应内容开头是否是正常的 JavaScript 代码而不是 HTML 报错页面。4.4 页面能打开但接口请求发出后跨域报错当你在/docs页面点击 Try it out 执行请求时浏览器会从你的页面地址向 API 地址发起请求。如果两者协议、域名、端口任一不同就属于跨域浏览器默认会拦截。FastAPI 处理跨域的方式是通过CORSMiddleware中间件。离线内网环境下这个问题的排查思路和公网一样from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[*], allow_credentialsTrue, allow_methods[*], allow_headers[*], )注意在纯内网环境里可以用allow_origins[*]放宽限制这比公网环境安全风险低得多。如果公司有具体的安全规范再按规范收紧即可。加了中间件之后记得重启服务再测试。4.5 OpenAPI JSON 里包含内网地址但客户端访问不了还有一类情况和docs页面无关但会让你误以为是文档显示问题FastAPI 在生成 OpenAPI 文档时接口的请求地址是基于request.base_url来确定的。如果你在内网用http://192.168.1.10:8000访问那么文档里接口的 server 地址就是http://192.168.1.10:8000。这个地址只有你的终端能访问。如果你的应用还需要从一个网关、域名或者另一个网段访问而那个地址客户端不可达那么即使docs页面渲染成功了点击接口发出的请求还是会失败。解决办法是在创建 FastAPI 实例时指定servers参数app FastAPI( docs_urlNone, redoc_urlNone, servers[{url: http://your-internal-api.example.com}] )这样无论用户用什么地址访问/docs文档里的接口请求地址都会指向你配置的那个内网 API 地址。这个细节在一次多网段环境的部署中救了我一次因为不同网段的用户访问同一个应用前端生成的地址完全不同不统一指定服务器地址文档对一部分人来说就是不可用的。5. 进一步优化关于 ReDoc 和 Swagger UI 的应用细节5.1 ReDoc 的离线化处理FastAPI 默认还提供了一个 ReDoc 风格的文档页面/redoc。ReDoc 同样是从 CDN 加载资源离线环境一样会白屏。如果你不需要 ReDoc直接在创建应用时传redoc_urlNone即可。如果需要保留处理方式跟 Swagger UI 类似也需要下载对应的静态资源。ReDoc 的官方发布包是redocnpm 安装后复制redoc.standalone.js到静态目录然后在自定义路由中引入即可。不再赘述。5.2 Swagger UI 页面打不开时的最快速方法还有一种取巧的快速方法只适用于“你对安全要求不高、只是临时应急”的场景在服务器上跑一个定时任务定期去外网 CDN 拉取 Swagger UI 资源到本地 Nginx 目录再把 Nginx 的cdn.jsdelivr.net这个域名的解析指向本机。这样浏览器访问 CDN 域名时其实是在内网 Nginx 拿到了文件。这个方法的好处是不需要改 FastAPI 代码坏处是绕了一圈而且如果你没有 Nginx 控制权就白搭。所以我还是推荐直接在 FastAPI 应用内部解决一劳永逸。5.3 配合docs_urlNone的隐藏式文档有些团队在正式环境不想对外开放接口文档但又希望内网调试时能用。这时可以进一步改造把 docs 路由绑定到特定网段或增加鉴权。比如from fastapi import Request, HTTPException app.get(/docs, include_in_schemaFalse) async def custom_docs(request: Request): # 简单的IP白名单示例实际用 Auth 更好 client_host request.client.host if not client_host.startswith(192.168.): raise HTTPException(status_code403, detailForbidden) return HTMLResponse(...)这样内网同事正常访问非内网来源直接拒绝。不要把这个当成安全方案它只能挡君子挡不住恶意构造来源 IP 的攻击者。真正要保护好文档还是应该接入统一的认证中心。5.4 多环境配置的经验我这边通常的做法是用环境变量或配置文件控制 docs 是否启用。开发环境直接用默认/docs生产恢复自定义离线 HTML。比如import os ENV os.getenv(APP_ENV, dev) if ENV prod: app FastAPI(docs_urlNone, redoc_urlNone) app.mount(/static, StaticFiles(directorystatic), namestatic) # 注册自定义 /docs 路由 else: app FastAPI()这种写法好处是开发时不用关掉默认文档生产时又能确保离线可用。你可以在dev环境用默认在线 CDN 快速验证功能在prod环境用离线资源保证稳定。6. 几个容易被忽略的细节6.1 关于/openapi.json的缓存有些浏览器会缓存/openapi.json的响应。当你改了接口定义后刷新/docs页面如果发现有更新但部分改动没生效可能是缓存问题。可以强制刷新CtrlShiftR或给/openapi.json响应加Cache-Control: no-cache头。用 FastAPI 实现也不难from fastapi.responses import JSONResponse app.get(/openapi.json, include_in_schemaFalse) async def openapi_spec(): return JSONResponse( contentapp.openapi(), headers{Cache-Control: no-cache} )注意这里重写了默认的/openapi.json路由返回内容仍然来自app.openapi()所以接口列表和参数定义都是自动生成的不影响功能。6.2 容器化部署时的文件拷贝如果你的 FastAPI 是通过 Docker 部署的记得把static目录写进 Dockerfile。不要依赖运行时的网络去拉资源。一个简单的 Dockerfile 片段示例FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]这里的COPY . .会把静态资源一起拷进镜像。如果你用了.dockerignore记得检查是否忽略了static目录别把静态资源挡在镜像外。6.3 注意docs_urlNone后OpenAPI 文件路径依然有效有人会担心把docs_urlNone之后/openapi.json是不是也不可访问了。实际上不会。docs_url和redoc_url只影响这两个 HTML 页面路由/openapi.json是默认 openapi 路由独立存在。所以你可以放心地关掉默认 docs再自定义openapi 接口本身不会受影响。这一点我在验证时也确认过。6.4 自定义 favicon 的简单方式如果公司内部有统一品牌要求可以把favicon-32x32.png替换成自己的 logo。这一步很简单覆盖静态目录下的同名文件即可。如果你不想替换文件也可以直接在 HTML 里改路径指向另一个静态资源。7. 实测心得这套方案在不同场景下的表现这套离线化方案我在几类项目里都验证过第一类是单机内网部署的轻量 API 服务服务器不能上外网客户端也不能上外网。把static目录和主程序放在一起用 systemd 或 supervisor 启动/docs页面秒开和本地开发没什么区别。第二类是 Docker 容器部署且服务器与客户端都不通外网。这种方式我把静态文件打进镜像应用启动后通过 Docker 端口映射访问一切正常。第三类是服务器能上外网、但客户端只能访问内网的半隔离环境。这种情况下 FastAPI 默认的docs页面依然崩溃因为浏览器的 JS 资源请求走的是客户端网络。这一点让人印象非常深刻问题根源不在服务器而在浏览器的网络出口所以判断问题时不要被服务器的网络状态误导。有一次线上事故排查服务器所有端口、外网都通但用户反馈 API 文档打不开。现场抓包发现浏览器发起了一个对cdn.jsdelivr.net的 HTTPS 请求被办公网络策略拦截直接 reset。当时就理解了这个问题的本质是“浏览器代码加载路径”跟服务器通不通网是两码事。于是彻底放弃改 CDN 的方案直接走了本地化。另外因为把docs_urlNone之后团队里有一些人习惯用/docs的旧书签会导致打开报 404但这种处理其实是“文档已停用”的预期行为。如果希望彻底关闭文档同时也不想暴露这是最直接的入口管理方式如果希望内网用户看到就把自定义/docs注册得足够完整。8. 结尾小建议我个人在实际操作里还有一个小习惯把static/swagger-ui目录连同源文件打包成一个独立压缩包归档放到公司内部镜像仓库或制品库。这样任何新项目需要离线文档能力直接解压粘贴不需要重新去外网拉文件节省了很多重复劳动。如果你所在团队多个服务都用了 FastAPI也可以把这套离线资源做成一个公共的 base 项目模板大家统一引用版本一致维护成本低很多。另外Swagger UI 的版本升级节奏并不快但如果你打算定期更新尽量在升级后跑一遍完整的接口请求测试重点看“Try it out”功能是否正常多版本兼容的隐患通常是 JS 升级带来的行为差异。希望这套离线化方案能帮你彻底解决内网环境下/docs页面白屏的问题。如果你们的网络环境更特殊比如还涉及到网关层、多级代理或者统一认证处理思路是一样的把一切外部资源本地化把一切依赖明确化剩下的就只是顺着路由排查的耐心活了。