在 Debian 上部署或访问 Swagger(如 Swagger UI / springdoc-openapi / swagger-ui 静态资源) 时“慢”,通常不是 Swagger 本身的问题,而是环境、网络或配置导致的。下面按最常见原因逐一说明,并给出排查与解决办法。
swagger-ui-bundle.js
swagger-ui.css
很多 Swagger UI 默认从 CDN 加载 JS/CSS:
https://cdn.jsdelivr.net/npm/swagger-ui-dist/...
Debian 服务器如果:
就会导致页面极慢甚至打不开。
使用本地 Swagger UI 资源
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
</dependency>
默认已经是本地资源(不需要 CDN)
apt install unzip
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.x.zip
unzip v5.x.zip
cp -r swagger-ui-5.x/dist /var/www/html/swagger
Swagger UI 会请求:
localhost127.0.0.1如果 /etc/resolv.conf 配置不合理(如无效 DNS),会卡在解析阶段。
cat /etc/resolv.conf
nameserver 127.0.0.1
# 或
nameserver 8.8.8.8
/swagger-ui.html 才慢@OpenAPIDefinition(
info = @Info(title = "API", version = "1.0")
)
缩小扫描范围:
springdoc:
packages-to-scan: com.example.api
gzip on;
gzip_types application/javascript text/css;
curl 第一次很慢Debian 默认启用 IPv6,但网络不支持
# 临时
sysctl -w net.ipv6.conf.all.disable_ipv6=1
# 永久
vi /etc/sysctl.conf
net.ipv6.conf.all.disable_ipv6 = 1
| 场景 | 结果 |
|---|---|
| 无外网 + CDN | 极慢 |
| DNS 错误 | 首次慢 |
| IPv6 开启 | 连接慢 |
| Nginx 无 gzip | 加载慢 |
| 扫描全部包 | 启动慢 |
# 1. 是否访问外网
curl -I https://cdn.jsdelivr.net
# 2. DNS 是否正常
nslookup localhost
# 3. IPv6 是否关闭
ip a | grep inet6
# 4. Swagger 是否本地
浏览器 F12 → Network
你可以告诉我:
我可以直接给你针对性配置方案。