debian下swagger报错咋办

在 Debian 下使用 Swagger（无论是 Swagger UI、Swagger Editor，还是 Spring Boot / Node / Python 里集成的 Swagger）报错了，需要先看具体报错信息。不过我可以先给你一套通用排查思路，你对照看看是哪一类问题。

一、先确认“Swagger 是哪来的”

不同场景处理方式不一样：

Spring Boot + springfox / springdoc
Node.js（swagger-ui-express / swagger-jsdoc）
Python（FastAPI / flask-swagger）
直接部署 Swagger UI（Nginx / Apache）
Swagger Editor 本地运行

你可以先告诉我用的是哪一种。

二、Debian 下最常见的几类报错 & 解决办法

1️⃣ 端口 / 权限问题

现象

EADDRINUSE
无法访问 http://localhost:8080/swagger-ui.html

解决

# 查看端口占用
sudo netstat -tunlp | grep 8080

# 或用 lsof
sudo lsof -i:8080

# 杀掉占用进程
sudo kill -9 PID

如果是 80 / 443：

sudo setcap cap_net_bind_service=+ep /usr/bin/node

2️⃣ 依赖或版本不兼容（非常常见）

Spring Boot 场景

Spring Boot 3 → 用 springdoc-openapi
Spring Boot 2 → 用 springfox-swagger2

❌ 错误示例：

Unable to infer base url
No handler found for swagger-resources

✅ 解决：

<!-- Spring Boot 3 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

访问：

/swagger-ui/index.html

3️⃣ Node 环境报错（Debian + nvm）

现象

node: command not found
npm ERR! code EAI_AGAIN

解决

# 安装 node
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs

# 检查
node -v
npm -v

4️⃣ Swagger UI 打不开（Nginx）

现象

白屏
404
CORS 报错

Nginx 示例配置

location /swagger-ui/ {
    alias /opt/swagger-ui/;
    try_files $uri $uri/ /swagger-ui/index.html;
}

5️⃣ YAML / JSON 格式错误

现象

Resolver error
Could not resolve reference

解决

# 校验 swagger.yaml
npx @apidevtools/swagger-cli validate swagger.yaml

三、建议你下一步这样做

你可以直接把 报错信息原文 贴出来（越多越好），包括：

Debian 版本（cat /etc/os-release）
Swagger 类型
完整错误日志

我可以精准定位并给你改法。

如果你愿意，也可以直接说一句：

“我是 Debian + Spring Boot 3，访问 /swagger-ui 报 xxx”

我来对症下药。